Compaq AAQ2G1FTK User Manual

CompaqCOBOL UserManual

Order Number: AA–Q2G1F–TK

October 2000

This manual provides information to help you develop Compaq COBOL programs for the OpenVMS Alpha and Compaq Tru64 UNIX platforms.

Revision/Update Information: This manual supersedes the

DIGITAL COBOL User Manual, Version 2.5.

Operating System and Version: OpenVMS Alpha Version 6.2 or higher;

Tru64 UNIX Version 4.0F or higher

Software Version: Compaq COBOL Version 2.7

Compaq Computer Corporation Houston, Texas

Trademark Ofﬁce. OpenVMS and Tru64 are trademarks of Compaq Information Technologies Group, L.P. Microsoft, MS-DOS, Win32, Windows, and Windows NT are trademarks of Microsoft Corporation. Motif, OSF/1, UNIX, and X/Open are trademarks of The Open Group. All other product names mentioned herein may be trademarks of their respective companies. Conﬁdential computer software. Valid license from Compaq required for possession, use, or copying.

Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND WHETHER IN AN ACTION OF CONTRACT OR TORT, INCLUDING NEGLIGENCE.

The limited warranties for Compaq products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

This document was prepared using DECdocument, Version 3.3-1b.

ZK6297

Preface ............................................................ xxiii

1 Developing Compaq COBOL Programs

1.0.1 Files Installed on Your System ............................... 1–1

1.1 Compaq COBOL and Alpha Architecture System Resources ........... 1–2

1.1.1 Compilation Performance . . . ................................ 1–2

1.1.2 Tuning OpenVMS Alpha for Large Compaq COBOL Compiles ...... 1–3

1.1.2.1 Optimizing Virtual Memory Usage . . ....................... 1–3

1.1.2.2 Optimizing Physical Memory Usage. ....................... 1–4

1.1.2.3 Improving Compile Performance with Separate Compilation

(OpenVMS) . . ........................................ 1–6

1.1.3 Choosing a Reference Format ............................... 1–6

1.1.3.1 Terminal Reference Format .............................. 1–6

1.1.3.2 ANSI Reference Format . ................................ 1–7

1.1.3.3 Converting Between Reference Formats .................... 1–7

1.2 Developing Programs on Tru64 UNIX ............................ 1–7

1.2.1 Creating a Compaq COBOL Program on Tru64 UNIX ............. 1–7

1.2.2 Compiling a Compaq COBOL Program on Tru64 UNIX ............ 1–10

1.2.2.1 Format of the COBOL Command on Tru64 UNIX ............. 1–10

1.2.2.2 COBOL Command Flags ................................ 1–11

1.2.2.3 External File Handler Support ........................... 1–15

1.2.2.4 Specifying Multiple Files and Flags . ....................... 1–15

1.2.2.5 Compiling Multiple Files ................................ 1–15

1.2.2.6 Debugging a Program . . ................................ 1–16

1.2.2.7 Output Files: Object, Executable, Listing, and Temporary

Files ................................................ 1–16

1.2.2.8 Naming Output Files . . . ................................ 1–17

1.2.2.9 Temporary Files ....................................... 1–17

1.2.2.10 Examples of the COBOL Command . ....................... 1–17

1.2.2.11 Other Compilers....................................... 1–18

1.2.2.12 Interpreting Messages from the Compiler ................... 1–18

1.2.3 Linking a Compaq COBOL Program on Tru64 UNIX ............. 1–19

1.2.3.1 Specifying Object Libraries for Linking ..................... 1–19

1.2.3.2 Specifying Additional Object Libraries ...................... 1–20

1.2.3.3 Specifying Types of Object Libraries ....................... 1–21

1.2.3.4 Creating Shared Object Libraries . . ....................... 1–21

1.2.3.5 Shared Library Restrictions .............................. 1–22

1.2.3.6 Installing Shared Libraries .............................. 1–22

1.2.3.7 Interpreting Messages from the Linker ..................... 1–22

1.2.4 Running a Compaq COBOL Program on Tru64 UNIX ............. 1–23

1.2.4.1 Accessing Command-Line Arguments ...................... 1–23

1.2.4.2 Accessing Environment Variables . . ....................... 1–24

1.2.4.3 Errors and Switches.................................... 1–25

iii

1.2.5 Program Development Stages and Tools ....................... 1–25

1.3 Developing Programs on OpenVMS Alpha ......................... 1–27

1.3.1 Creating a Compaq COBOL Program on OpenVMS Alpha ......... 1–27

1.3.2 Compiling a Compaq COBOL Program on OpenVMS Alpha ........ 1–29

1.3.2.1 Format of the COBOL Command on OpenVMS Alpha.......... 1–29

1.3.2.2 Compiling Multiple Files ................................ 1–30

1.3.2.3 Debugging a Program .................................. 1–30

1.3.2.4 Separately Compiled Programs ........................... 1–31

1.3.2.5 COBOL Qualiﬁers . .................................... 1–31

1.3.2.6 Common Command-Line Errors to Avoid . ................... 1–35

1.3.2.7 Compiling Programs with Conditional Compilation . ........... 1–36

1.3.2.8 Interpreting Messages from the Compiler ................... 1–36

1.3.2.9 Using Compiler Listing Files ............................ 1–38

1.3.3 Linking a Compaq COBOL Program .......................... 1–39

1.3.3.1 The LINK Command ................................... 1–39

1.3.3.2 LINK Qualiﬁers . . .................................... 1–40

1.3.3.3 Specifying Modules Other than Compaq COBOL Modules....... 1–40

1.3.3.4 Specifying Object Module Libraries ........................ 1–41

1.3.3.5 Creating Shareable Images . . ............................ 1–43

1.3.3.6 Interpreting Messages from the Linker . ................... 1–47

1.3.4 Running a Compaq COBOL Program ......................... 1–48

1.3.4.1 Accessing Command-Line Arguments at Run Time . ........... 1–48

1.3.4.2 Accessing System Logicals at Run Time . ................... 1–49

1.3.4.3 Accessing Input and Output Devices at Run Time . . ........... 1–50

1.3.4.4 Debugging Environment ................................ 1–50

1.3.4.5 Interpreting Run-Time Messages ......................... 1–51

1.4 Program Run Messages . . . .................................... 1–52

1.4.1 Data Errors . ............................................ 1–52

1.4.2 Program Logic Errors. . .................................... 1–53

1.4.3 Run-Time Input/Output Errors . . ............................ 1–54

1.4.4 I/O Errors and RMS (OpenVMS) . ............................ 1–55

1.5 Using Program Switches . . .................................... 1–59

1.5.1 Setting and Controlling Switches Internally . ................... 1–60

1.5.2 Setting and Controlling Switches Externally ................... 1–60

1.6 Special Information for Year 2000 Programming . ................... 1–62

2 Handling Numeric Data

2.1 How the Compiler Stores Numeric Data .......................... 2–1

2.2 Specifying Alignment ......................................... 2–1

2.3 Sign Conventions ............................................ 2–2

2.4 Invalid Values in Numeric Items ................................ 2–2

2.5 Evaluating Numeric Items . .................................... 2–3

2.5.1 Numeric Relation Test . .................................... 2–3

2.5.2 Numeric Sign Test ........................................ 2–4

2.5.3 Numeric Class Tests. . . .................................... 2–4

2.5.4 Success/Failure Tests . . .................................... 2–5

2.6 Using the MOVE Statement ................................... 2–6

2.6.1 Elementary Numeric Moves ................................. 2–6

2.6.2 Elementary Numeric-Edited Moves ........................... 2–7

2.6.3 Subscripted Moves ........................................ 2–9

2.6.4 Common Move Errors . .................................... 2–9

2.7 Using the Arithmetic Statements................................ 2–9

2.7.1 Temporary Work Items . .................................... 2–9

2.7.2 Standard and Native Arithmetic ............................. 2–10

2.7.2.1 Using the /MATH_INTERMEDIATE Qualiﬁer . ............... 2–10

2.7.2.2 Using the /ARITHMETIC Qualiﬁer . ....................... 2–12

2.7.3 Specifying a Truncation Qualiﬁer ............................. 2–12

2.7.4 Using the ROUNDED Phrase ............................... 2–12

2.7.4.1 ROUNDED with REMAINDER ........................... 2–13

2.7.5 Using the SIZE ERROR Phrase .............................. 2–13

2.7.6 Using the GIVING Phrase . . ................................ 2–14

2.7.7 Multiple Operands in ADD and SUBTRACT Statements........... 2–14

2.7.8 Common Errors in Arithmetic Statements ...................... 2–15

3 Handling Nonnumeric Data

3.1 Storage of Nonnumeric Data . . . ................................ 3–1

3.2 Data Organization . . . ........................................ 3–2

3.2.1 Group Items ............................................. 3–2

3.2.2 Elementary Items ........................................ 3–2

3.3 Special Characters . . . ........................................ 3–3

3.4 Testing Nonnumeric Items ..................................... 3–3

3.4.1 Relation Tests of Nonnumeric Items . . . ....................... 3–3

3.4.1.1 Classes of Data ....................................... 3–4

3.4.1.2 Comparison Operations . ................................ 3–5

3.4.2 Class Tests for Nonnumeric Items ............................ 3–5

3.5 Data Movement ............................................. 3–6

3.6 Using the MOVE Statement . . . ................................ 3–7

3.6.1 Group Moves ............................................ 3–7

3.6.2 Elementary Moves ........................................ 3–7

3.6.2.1 Edited Moves . ........................................ 3–9

3.6.2.2 Justiﬁed Moves ....................................... 3–9

3.6.3 Multiple Receiving Items . . . ................................ 3–10

3.6.4 Subscripted Moves ........................................ 3–10

3.6.5 Common Nonnumeric Item MOVE Statement Errors ............. 3–11

3.6.6 Using the MOVE CORRESPONDING Statement for Nonnumeric

Items . . ................................................ 3–11

3.6.7 Using Reference Modiﬁcation ................................ 3–12

4 Handling Tables

4.1 Deﬁning Tables ............................................. 4–1

4.1.1 Deﬁning Fixed-Length, One-Dimensional Tables . . ............... 4–1

4.1.2 Deﬁning Fixed-Length, Multidimensional Tables. . ............... 4–4

4.1.3 Deﬁning Variable-Length Tables ............................. 4–5

4.1.4 Storage Allocation for Tables ................................ 4–6

4.1.4.1 Using the SYNCHRONIZED Clause ....................... 4–7

4.2 Initializing Values of Table Elements ............................. 4–10

4.3 Accessing Table Elements ..................................... 4–12

4.3.1 Subscripting ............................................. 4–12

4.3.2 Subscripting with Literals . . ................................ 4–13

4.3.3 Subscripting with Data Names .............................. 4–14

4.3.4 Subscripting with Indexes . . ................................ 4–14

4.3.5 Relative Indexing . ........................................ 4–15

4.3.6 Index Data Items . ........................................ 4–16

4.3.7 Assigning Index Values Using the SET Statement................ 4–16

4.3.7.1 Assigning an Integer Index Value with a SET Statement ....... 4–16

4.3.7.2 Incrementing an Index Value with the SET Statement ......... 4–16

4.3.8 Identifying Table Elements Using the SEARCH Statement ......... 4–16

4.3.8.1 Implementing a Sequential Search ........................ 4–17

4.3.8.2 Implementing a Binary Search ........................... 4–18

5 Using the STRING, UNSTRING, and INSPECT Statements

5.1 Concatenating Data Using the STRING Statement .................. 5–1

5.1.1 Multiple Sending Items .................................... 5–1

5.1.2 Using the DELIMITED BY Phrase ........................... 5–2

5.1.3 Using the POINTER Phrase ................................ 5–4

5.1.4 Using the OVERFLOW Phrase . . ............................ 5–4

5.1.5 Common STRING Statement Errors .......................... 5–6

5.2 Separating Data Using the UNSTRING Statement .................. 5–6

5.2.1 Multiple Receiving Items ................................... 5–6

5.2.2 Controlling Moved Data Using the DELIMITED BY Phrase ........ 5–8

5.2.2.1 Multiple Delimiters .................................... 5–12

5.2.3 Using the COUNT Phrase .................................. 5–12

5.2.4 Saving UNSTRING Delimiters Using the DELIMITER Phrase . . . . . . 5–13

5.2.5 Controlling UNSTRING Scanning Using the POINTER Phrase . . . . . 5–14

5.2.6 Counting UNSTRING Receiving Items Using the TALLYING

Phrase ................................................. 5–15

5.2.7 Exiting an UNSTRING Statement Using the OVERFLOW Phrase . . . 5–16

5.2.8 Common UNSTRING Statement Errors ....................... 5–16

5.3 Examining and Replacing Characters Using the INSPECT Statement . . . 5–17

5.3.1 Using the TALLYING and REPLACING Options of the INSPECT

Statement . . ............................................ 5–17

5.3.2 Restricting Data Inspection Using the BEFORE/AFTER Phrase . . . . . 5–18

5.3.3 Implicit Redeﬁnition . . .................................... 5–18

5.3.4 Examining the INSPECT Operation .......................... 5–21

5.3.4.1 Setting the Scanner .................................... 5–22

5.3.4.2 Active/Inactive Arguments . . . ............................ 5–22

5.3.4.3 Finding an Argument Match . ............................ 5–23

5.3.5 The TALLYING Phrase .................................... 5–24

5.3.5.1 The Tally Counter . .................................... 5–24

5.3.5.2 The Tally Argument .................................... 5–24

5.3.5.3 The Tally Argument List ................................ 5–25

5.3.5.4 Interference in Tally Argument Lists ....................... 5–27

5.3.6 Using the REPLACING Phrase . . ............................ 5–30

5.3.6.1 The Search Argument .................................. 5–30

5.3.6.2 The Replacement Value ................................. 5–31

5.3.6.3 The Replacement Argument . . ............................ 5–31

5.3.6.4 The Replacement Argument List .......................... 5–31

5.3.6.5 Interference in Replacement Argument Lists ................. 5–32

5.3.7 Using the CONVERTING Option. ............................ 5–33

5.3.8 Common INSPECT Statement Errors ......................... 5–33

6 Processing Files and Records

6.1 Deﬁning Files and Records .................................... 6–1

6.1.1 File Organization . ........................................ 6–2

6.1.2 Record Format . . . ........................................ 6–8

6.1.3 File Design .............................................. 6–13

6.2 Identifying Files and Records from Within Your Compaq COBOL

Program................................................... 6–14

6.2.1 Deﬁning a File Connector . . ................................ 6–14

6.2.2 Specifying File Organization and Record Access Mode............. 6–20

6.3 Creating and Processing Files . . ................................ 6–24

6.3.1 Opening and Closing Files . . ................................ 6–24

6.3.2 File Handling for Sequential and Line Sequential Files ........... 6–26

6.3.3 File Handling for Relative Files .............................. 6–29

6.3.4 File Handling for Indexed Files .............................. 6–32

6.4 Reading Files ............................................... 6–37

6.4.1 Reading a Sequential or Line Sequential File ................... 6–37

6.4.2 Reading a Relative File .................................... 6–38

6.4.3 Reading an Indexed File . . . ................................ 6–42

6.5 Updating Files .............................................. 6–48

6.5.1 Updating a Sequential or Line Sequential File . . . ............... 6–48

6.5.2 Updating a Relative File . . . ................................ 6–50

6.5.2.1 Rewriting a Relative File ................................ 6–50

6.5.2.2 Deleting Records from a Relative File ...................... 6–53

6.5.3 Updating an Indexed File . . ................................ 6–55

6.6 Backing Up Your Files ........................................ 6–60

7 Handling Input/Output Exception Conditions

7.1 Planning for the AT END Condition ............................. 7–2

7.2 Planning for the Invalid Key Condition ........................... 7–2

7.3 Using File Status Values and OpenVMS RMS Completion Codes ....... 7–3

7.3.1 File Status Values ........................................ 7–4

7.3.2 RMS Completion Codes (OpenVMS) . . . ....................... 7–5

7.4 Using Declarative USE Procedures .............................. 7–8

8 Sharing Files and Locking Records

8.1 Controlling Access to Files and Records ........................... 8–1

8.2 Choosing X/Open Standard or Compaq Standard File Sharing and Record

Locking . . . ................................................ 8–3

8.3 Ensuring Successful File Sharing ............................... 8–4

8.3.1 Providing Disk Residency. . . ................................ 8–4

8.3.2 Using File Protection ..................................... 8–4

8.3.3 Determining the Intended Access Mode to a File . . ............... 8–6

8.3.4 Specifying File Access Using X/Open Standard File Sharing . ....... 8–6

8.3.5 Specifying File Access Using Compaq Standard File Sharing ....... 8–8

8.3.6 Error Handling for File Sharing ............................. 8–12

8.4 Ensuring Successful Record Locking ............................. 8–16

8.4.1 X/Open Standard Record Locking ............................ 8–17

8.4.2 Compaq Standard Record Locking ........................... 8–18

8.4.3 Error Handling for Record Locking ........................... 8–23

vii

9 Using the SORT and MERGE Statements

9.1 Sorting Data with the SORT Statement .......................... 9–1

9.1.1 File Organization Considerations for Sorting . ................... 9–2

9.1.2 Specifying Sort Parameters with the ASCENDING and

DESCENDING KEY Phrases ................................ 9–3

9.1.3 Resequencing Files with the USING and GIVING Phrases ......... 9–3

9.1.4 Manipulating Data Before and After Sorting with the INPUT

PROCEDURE and OUTPUT PROCEDURE Phrases . . . ........... 9–3

9.1.5 Maintaining the Input Order of Records Using the WITH

DUPLICATES IN ORDER Phrase ............................ 9–6

9.1.6 Specifying Non-ASCII Collating Sequences with the COLLATING

SEQUENCE IS Alphabet-Name Phrase ........................ 9–7

9.1.7 Multiple Sorting .......................................... 9–7

9.1.8 Sorting Variable-Length Records . ............................ 9–8

9.1.9 Preventing I/O Aborts . .................................... 9–9

9.1.10 Sorting Tables ........................................... 9–9

9.1.11 Sorting at the Operating System Level ........................ 9–9

9.2 Merging Data with the MERGE Statement ........................ 9–10

9.3 Sample Programs Using the SORT and MERGE Statements .......... 9–10

10 Producing Printed Reports

10.1 Designing a Report .......................................... 10–1

10.2 Components of a Report . . . .................................... 10–1

10.3 Accumulating and Reporting Totals . . ............................ 10–4

10.4 The Logical Page and the Physical Page .......................... 10–5

10.5 Programming a Conventional File Report ......................... 10–6

10.5.1 Deﬁning the Logical Page in a Conventional Report . . . ........... 10–6

10.5.2 Controlling the Spacing in a Conventional Report ................ 10–7

10.5.3 Advancing to the Next Logical Page in a Conventional Report . . . . . . 10–7

10.5.3.1 Programming for the Page-Overﬂow Condition in a Conventional

Report . . ............................................ 10–7

10.5.3.2 Using a Line Counter................................... 10–8

10.5.4 Printing the Conventional Report ............................ 10–9

10.5.5 A Conventional File Report Example .......................... 10–9

10.6 Programming a Linage-File Compaq COBOL Report ................. 10–12

10.6.1 Deﬁning the Logical Page in a Linage-File Report ................ 10–13

10.6.2 Controlling the Spacing in a Linage-File Report ................. 10–14

10.6.3 Using the LINAGE-COUNTER . . ............................ 10–14

10.6.4 Advancing to the Next Logical Page in a Linage-File Report ........ 10–14

10.6.5 Programming for the End-of-Page and Page-Overﬂow Condition . . . . . 10–15

10.6.6 Printing a Linage-File Report . . . ............................ 10–19

10.6.7 A Linage-File Report Example . . . ............................ 10–20

10.7 Modes for Printing Reports .................................... 10–23

10.7.1 Directly Allocating a Printer ................................ 10–23

10.7.2 Spooling to a Mass Storage Device ............................ 10–24

10.8 Programming a Report Writer Report ............................ 10–24

10.8.1 Using the REPORT Clause in the File Section .................. 10–25

10.8.2 Deﬁning the Report Section and the Report File ................. 10–25

10.8.3 Deﬁning a Report Writer Logical Page with the PAGE Clause . . . . . . 10–25

10.8.4 Describing Report Group Description Entries ................... 10–26

10.8.5 Vertical Spacing for the Logical Page .......................... 10–29

10.8.6 Horizontal Spacing for the Logical Page ....................... 10–30

10.8.7 Assigning a Value in a Print Line ............................ 10–31

viii

10.8.8 Deﬁning the Source for a Print Field . . . ....................... 10–31

10.8.9 Specifying Multiple Reports . ................................ 10–32

10.8.10 Generating and Controlling Report Headings and Footings . . ....... 10–32

10.8.11 Deﬁning and Incrementing Totals ............................ 10–34

10.8.11.1 Subtotaling . . ........................................ 10–34

10.8.11.2 Crossfooting . . ........................................ 10–35

10.8.11.3 Rolling Forward ....................................... 10–35

10.8.11.4 RESET Option ........................................ 10–36

10.8.11.5 UPON Option . ........................................ 10–36

10.8.12 Restricting Print Items .................................... 10–37

10.8.13 Processing a Report Writer Report ............................ 10–38

10.8.13.1 Initiating the Report . . . ................................ 10–38

10.8.13.2 Generating a Report Writer Report . ....................... 10–39

10.8.13.3 Automatic Operations of the GENERATE Statement . . . ....... 10–39

10.8.13.4 Ending Report Writer Processing . . . ....................... 10–40

10.8.13.5 Applying the USE BEFORE REPORTING Statement . . . ....... 10–41

10.8.13.6 Suppressing a Report Group ............................. 10–42

10.8.14 Selecting a Report Writer Report Type. . ....................... 10–42

10.8.14.1 Detail Reporting....................................... 10–42

10.8.14.2 Summary Reporting .................................... 10–43

10.9 Report Writer Examples ....................................... 10–43

10.9.1 Input Data .............................................. 10–43

10.9.2 EX1006—Detail Report Program ............................. 10–44

10.9.3 EX1007—Detail Report Program ............................. 10–49

10.9.4 EX1008—Detail Report Program ............................. 10–57

10.9.5 EX1009—Detail Report Program ............................. 10–65

10.9.6 EX1010—Summary Report Program . . . ....................... 10–74

10.10 Solving Report Problems ...................................... 10–82

10.10.1 Printing More Than One Logical Line on a Single Physical Line ..... 10–82

10.10.2 Group Indicating . ........................................ 10–87

10.10.3 Fitting Reports on the Page . ................................ 10–88

10.10.4 Printing Totals Before Detail Lines ........................... 10–88

10.10.5 Underlining Items in Your Reports ........................... 10–89

10.10.6 Bolding Items in Your Reports ............................... 10–89

11 Using ACCEPT and DISPLAY Statements for Input/Output and

Video Forms

11.1 Using ACCEPT and DISPLAY for I/O ............................ 11–1

11.2 Designing Video Forms with ACCEPT and DISPLAY Statement

Extensions . ................................................ 11–3

11.2.1 Clearing a Screen Area .................................... 11–4

11.2.2 Horizontal and Vertical Positioning of the Cursor . ............... 11–5

11.2.3 Assigning Character Attributes to Your Format Entries ........... 11–8

11.2.4 Using the CONVERSION Phrase to Display Numeric Data . ....... 11–9

11.2.5 Handling Data with ACCEPT Options . . ....................... 11–12

11.2.5.1 Using CONVERSION with ACCEPT Data................... 11–12

11.2.5.2 Using ON EXCEPTION When Accepting Data with

CONVERSION ........................................ 11–13

11.2.5.3 Protecting the Screen . . . ................................ 11–14

11.2.5.4 Using NO ECHO with ACCEPT Data ...................... 11–16

11.2.5.5 Assigning Default Values to Data Fields .................... 11–16

11.2.6 Using Terminal Keys to Deﬁne Special Program Functions . . ....... 11–20

11.2.7 Using the EDITING Phrase . ................................ 11–28

11.3 Designing Video Forms with Screen Section ACCEPT and DISPLAY . . . . 11–31

11.3.1 Using Screen Section Options . . . ............................ 11–32

11.3.1.1 Comparison of Screen Section Extensions with Other Extensions

of ACCEPT and DISPLAY . . . ............................ 11–34

12 Interprogram Communication

12.1 Multiple COBOL Program Run Units ............................ 12–1

12.1.1 Examples of COBOL Run Units . . ............................ 12–1

12.1.2 Calling Procedures ........................................ 12–2

12.2 COBOL Program Attributes .................................... 12–3

12.2.1 The INITIAL Clause . . .................................... 12–4

12.2.2 The EXTERNAL Clause .................................... 12–5

12.3 Transferring Flow of Control ................................... 12–5

12.3.1 The CALL Statement . . .................................... 12–5

12.3.2 Nesting CALL Statements .................................. 12–6

12.3.3 The EXIT PROGRAM Statement . ............................ 12–8

12.4 Accessing Another Program’s Data Division........................ 12–8

12.4.1 The USING Phrase . . . .................................... 12–9

12.4.2 The Linkage Section . . .................................... 12–12

12.5 Communicating with Contained COBOL Programs ................. 12–13

12.5.1 The COMMON Clause . .................................... 12–14

12.5.2 The GLOBAL Clause . . .................................... 12–15

12.5.2.1 Sharing GLOBAL Data ................................. 12–15

12.5.2.2 Sharing GLOBAL Files ................................. 12–15

12.5.2.3 Sharing USE Procedures ................................ 12–16

12.5.2.4 Sharing Other Resources ................................ 12–18

12.6 Calling Compaq COBOL Programs from Other Languages . ........... 12–19

12.6.1 Calling COBOL Programs from C ............................ 12–19

12.7 Calling Non-COBOL Programs from Compaq COBOL ................ 12–25

12.7.1 Calling a Fortran Program .................................. 12–25

12.7.2 Calling a BASIC Program .................................. 12–27

12.7.3 Calling a C Program . . .................................... 12–29

12.8 Special Considerations for Interprogram Communication . . ........... 12–30

12.8.1 CALL and CANCEL Arguments . ............................ 12–30

12.8.2 Calling OpenVMS Alpha Shareable Images (OpenVMS) ........... 12–30

12.8.3 Calling Tru64 UNIX Shareable Objects (Tru64 UNIX) . . ........... 12–30

12.8.4 Case Sensitivity on Tru64 UNIX and Windows NT ............... 12–30

12.8.4.1 Linker Case Sensitivity ................................. 12–30

12.8.4.2 Calling C Programs from Compaq COBOL on Tru64 UNIX and

Windows NT ......................................... 12–31

12.8.4.3 Calling COBOL Programs from C on Tru64 UNIX and Windows

NT ................................................ 12–31

12.8.5 Additional Information . .................................... 12–32

13 Using Compaq COBOL in the Alpha Common Language

Environment

13.1 Routines, Procedures, and Functions . ............................ 13–1

13.2 The OpenVMS Alpha Calling Standard (OpenVMS) ................. 13–2

13.2.1 Register and Stack Usage .................................. 13–2

13.2.2 Return of the Function Value ................................ 13–3

13.2.3 The Argument List ........................................ 13–3

13.3 OpenVMS Alpha System Routines (OpenVMS) . . ................... 13–3

13.3.1 OpenVMS Alpha Run-Time Library Routines ................... 13–4

13.3.2 System Services . . ........................................ 13–4

13.4 Calling Routines ............................................ 13–5

13.4.1 Determining the Type of Call (OpenVMS) ...................... 13–5

13.4.2 Deﬁning the Argument (OpenVMS) ........................... 13–6

13.4.3 Calling the External Routine (OpenVMS) ...................... 13–7

13.4.4 Calling System Routines (OpenVMS) . . . ....................... 13–8

13.4.4.1 System Routine Arguments (OpenVMS) .................... 13–8

13.4.4.2 Calling a System Routine in a Function Call (OpenVMS) ....... 13–11

13.4.4.3 Calling a System Routine in a Procedure Call (OpenVMS) ...... 13–13

13.4.5 Checking the Condition Value (OpenVMS) ...................... 13–13

13.4.5.1 Library Return Status and Condition Value Symbols

(OpenVMS) . . ........................................ 13–15

13.4.6 Locating the Result (OpenVMS) .............................. 13–15

13.5 Establishing and Removing User Condition Handlers (OpenVMS) ...... 13–15

13.6 Examples (OpenVMS) ........................................ 13–19

14 Using the REFORMAT Utility

14.1 Running the REFORMAT Utility ................................ 14–1

14.2 ANSI-to-Terminal Format Conversion ............................ 14–2

14.3 Terminal-to-ANSI Format Conversion ............................ 14–3

14.4 REFORMAT Error Messages . . . ................................ 14–4

15 Optimizing Your Compaq COBOL Program

15.1 Specifying Optimization on the Compiler Command Line ............. 15–1

15.2 Specifying Alignment of Data for Optimum Performance ............. 15–5

15.3 Using COMP Data Items for Speed ............................. 15–5

15.4 Other Ways to Improve the Performance of Operations on Numeric

Data ...................................................... 15–7

15.4.1 Mixing Scale Factors and Data Types . . ....................... 15–7

15.4.2 Limiting Signiﬁcant Digits . . ................................ 15–7

15.4.3 Reducing the Compexity of Arithmetic Expressions ............... 15–7

15.4.4 Selection of Data Types (OpenVMS)........................... 15–8

15.5 Choices in Procedure Division Statements . . ....................... 15–8

15.5.1 Using GO TO DEPENDING ON Instead of IF, GO TO ............ 15–8

15.5.2 Using Indexing Instead of Subscripting . ....................... 15–9

15.5.3 Using SEARCH ALL Instead of SEARCH ...................... 15–9

15.5.4 Selecting Hypersort for Sorting Tasks . . ....................... 15–9

15.5.5 Minimizing USE Procedures with LINKAGE SECTION References

....................................................... 15–10

15.6 I/O Operations ............................................. 15–10

15.6.1 Using the APPLY Clause . . ................................ 15–10

15.6.1.1 Using the PREALLOCATION Phrase of the APPLY Clause ..... 15–10

15.6.1.2 Using the EXTENSION Phrase of the APPLY Clause . . . ....... 15–11

15.6.1.3 Using the DEFERRED-WRITE Phrase of the APPLY Clause .... 15–11

15.6.1.4 Using the FILL-SIZE ON Phrase of the APPLY Clause . . ....... 15–12

15.6.1.5 Using the WINDOW Phrase of the APPLY Clause............. 15–12

15.6.2 Using Multiple Buffers ..................................... 15–12

15.6.3 Sharing Record Areas ..................................... 15–13

15.6.4 Using COMP Unsigned Longword Integers ..................... 15–15

15.7 Optimizing File Design (OpenVMS) .............................. 15–15

15.7.1 Sequential Files . . ........................................ 15–15

15.7.2 Relative Files ............................................ 15–16

15.7.2.1 Maximum Record Number (MRN) ......................... 15–16

15.7.2.2 Cell Size . ............................................ 15–16

15.7.2.3 Bucket Size .......................................... 15–17

15.7.2.4 File Size . ............................................ 15–18

15.7.3 Indexed Files ............................................ 15–19

15.7.3.1 Optimizing Indexed File I/O. . ............................ 15–20

15.7.3.2 Calculating Key Index Levels. ............................ 15–24

15.7.3.3 Caching Index Roots ................................... 15–25

15.8 Image Activation Optimization (Tru64 UNIX) . . . ................... 15–25

16 Managing Memory and Data Access

16.1 Managing Memory Granularity ................................. 16–1

16.2 Using the VOLATILE Compiler Directive ......................... 16–3

16.3 Aligning Data for Performance and Compatibility ................... 16–3

16.3.1 Data Boundaries ......................................... 16–3

16.3.2 Data Field Padding . . . .................................... 16–4

16.3.3 Alignment Directives, Qualiﬁers, and Flags . ................... 16–4

16.3.4 Specifying Alignment at Compile Time ........................ 16–5

16.4 Using Alignment Directives, Qualiﬁers, and Flags .................. 16–6

16.4.1 Order of Alignment Operations . . ............................ 16–6

16.4.2 Nesting Alignment Directives . . . ............................ 16–7

16.4.3 Comparing Alignment Directive Effects ........................ 16–8

A Compiler Implementation Speciﬁcations

B Compaq COBOL for OpenVMS VAX and Compaq COBOL

Compatibility and Migration

B.1 Compatibility Matrix ......................................... B–1

B.2 Differences in Extensions and Other Features . . . ................... B–3

B.3 Command-Line Qualiﬁers (Options or Flags) ....................... B–4

B.3.1 Qualiﬁers and Flags Shared by Compaq COBOL and Compaq COBOL

for OpenVMS VAX . . . .................................... B–5

B.3.2 Compaq COBOL Speciﬁc Qualiﬁers and Flags ................... B–6

B.3.3 Qualiﬁers Only on Compaq COBOL for OpenVMS VAX ........... B–8

B.4 Compaq COBOL and Compaq COBOL for OpenVMS VAX Behavior

Differences ................................................. B–10

B.4.1 Program Structure Messages ................................ B–10

B.4.2 Program Listing Differences ................................ B–11

B.4.2.1 Machine Code ........................................ B–11

B.4.2.2 Module Names ........................................ B–11

B.4.2.3 COPY and REPLACE Statements ......................... B–11

B.4.2.4 Multiple COPY Statements . . ............................ B–12

B.4.2.5 COPY Insert Statement ................................. B–13

B.4.2.6 REPLACE and COPY REPLACING Statements . . . ........... B–14

B.4.2.7 DATE COMPILED Statement ............................ B–15

B.4.2.8 Compiler Listings and Separate Compilations (OpenVMS) . . . . . . B–15

B.4.3 Output Formatting ........................................ B–16

xii

B.4.4 Compaq COBOL and Compaq COBOL for OpenVMS VAX Statement

Differences .............................................. B–16

B.4.4.1 ACCEPT and DISPLAY Statements. ....................... B–16

B.4.4.2 LINAGE Clause ....................................... B–17

B.4.4.3 MOVE Statement...................................... B–18

B.4.4.4 SEARCH Statement .................................... B–18

B.4.5 System Return Codes ...................................... B–18

B.4.6 Diagnostic Messages ...................................... B–20

B.4.7 Storage for Double-Precision Data Items ....................... B–21

B.4.8 File Status Values ........................................ B–21

B.4.9 RMS Special Registers (OpenVMS) ........................... B–21

B.4.10 Calling Shareable Images . . ................................ B–22

B.4.11 Sharing Common Blocks (OpenVMS) . . . ....................... B–22

B.4.12 Arithmetic Operations ..................................... B–23

B.5 Compaq COBOL Differences Across Operating Systems .............. B–24

B.5.1 REWRITE .............................................. B–25

B.5.2 File Sharing and Record Locking ............................. B–25

B.5.3 VFC File Format . ........................................ B–26

B.5.4 File Attribute Checking .................................... B–26

B.5.5 Indexed Files ............................................ B–26

B.5.6 RMS Special Register References in Your Code . . . ............... B–27

B.5.7 Time and Fractional Seconds ............................... B–27

B.6 File Compatibility Across Languages and Platforms . . ............... B–27

B.7 LIB$INITIALIZE Interaction Between C and COBOL . ............... B–28

B.8 Reserved Words ............................................. B–28

B.9 Debugger Support Differences . ................................ B–29

B.10 DECset/LSE Support Differences ................................ B–29

B.11 DBMS Support .............................................. B–29

B.11.1 Compiling on Tru64 UNIX and Windows NT .................... B–29

B.11.2 Multistream DBMS DML . . . ................................ B–30

C Programming Productivity Tools

C.1 Compaq FUSE—an Integrated Development Environment (Tru64

UNIX) .................................................... C–1

C.2 Debugging Tools for Compaq COBOL Programs .................... C–2

C.3 Ladebug Debugger (Tru64 UNIX) ............................... C–4

C.4 OpenVMS Debugger (OpenVMS) ................................ C–8

C.4.1 Notes on Compaq COBOL Support ........................... C–8

C.4.2 Notes on Debugging Optimized Programs ...................... C–8

C.4.2.1 Separately Compiled Programs ........................... C–13

C.5 Language-Sensitive Editor (LSE) and the Source Code Analyzer (SCA)

(OpenVMS) ................................................ C–13

C.5.1 Notes on Compaq COBOL Support ........................... C–14

C.5.2 Preparing an SCA Library . . ................................ C–14

C.5.3 Starting and Terminating an LSE or an SCA Session ............. C–15

C.5.4 Compiling from Within LSE . ................................ C–15

C.6 Using Oracle CDD/Repository (OpenVMS) . . ....................... C–16

C.6.1 Creating Record and Field Deﬁnitions . . ....................... C–17

C.6.2 Accessing Oracle CDD/Repository Deﬁnitions from Compaq COBOL

Programs ............................................... C–18

C.6.3 Recording Dependencies.................................... C–19

C.6.4 Data Types.............................................. C–20

C.6.5 For More Information ..................................... C–22

xiii

D Porting to Compaq COBOL from Other Compilers

D.1 Porting Assistance ........................................... D–1

D.2 Flagged Foreign Extensions.................................... D–3

D.3 Implemented Extensions . . .................................... D–3

Index

Examples

1–1 Accessing Environment Variables and Command-Line Arguments . . . 1–24

1–2 Main Program and Subprograms . ............................ 1–45

1–3 Command Procedure to Link a Program as a Shareable Image . . . . . . 1–45

1–4 Accessing Logicals and Command-Line Arguments ............... 1–49

1–5 Using RMS Special Registers to Detect Errors (OpenVMS) ......... 1–56

1–6 Using RMS-CURRENT Special Registers to Detect Errors

(OpenVMS) . ............................................ 1–58

2–1 Success/Failure Test . . . .................................... 2–5

3–1 Item Concatenation Using Two MOVE Statements ............... 3–6

3–2 Sample Record Description Using the MOVE CORRESPONDING

Statement . . ............................................ 3–11

4–1 One-Dimensional Table .................................... 4–2

4–2 Multiple Data Items in a One-Dimensional Table ................ 4–2

4–3 Deﬁning a Table with an Index and an Ascending Search Key . . . . . . 4–3

4–4 Deﬁning a Two-Dimensional Table ............................ 4–4

4–5 Deﬁning a Three-Dimensional Table .......................... 4–5

4–6 Deﬁning a Variable-Length Table. ............................ 4–6

4–7 Sample Record Description Deﬁning a Table . ................... 4–7

4–8 Record Description Containing a COMP SYNC Item . . . ........... 4–8

4–9 Adding an Item Without Changing the Table Size ................ 4–8

4–10 How Adding 3 Bytes Adds 4 Bytes to the Element Length ......... 4–9

4–11 Initializing Tables with the VALUE Clause . . ................... 4–10

4–12 Initializing a Table with the OCCURS Clause ................... 4–10

4–13 Initializing Mixed Usage Items . . ............................ 4–11

4–14 Initializing Alphanumeric Items . ............................ 4–12

4–15 Using a Literal Subscript to Access a Table . . ................... 4–13

4–16 Subscripting a Multidimensional Table ........................ 4–13

4–17 Subscripting with Index Name Items .......................... 4–15

4–18 Sample Table ............................................ 4–19

4–19 A Serial Search .......................................... 4–20

4–20 Using SEARCH and Varying an Index Other than the First Index . . . 4–21

4–21 Using SEARCH and Varying an Index Data Item ................ 4–21

4–22 Using SEARCH and Varying an Index not Associated with the Target

Table .................................................. 4–22

4–23 Doing a Serial Search Without Using the VARYING Phrase ........ 4–22

4–24 A Multiple-Key, Binary Search . . . ............................ 4–23

5–1 Using the STRING Statement and Literals . . ................... 5–2

5–2 Sample Overﬂow Condition ................................. 5–5

xiv

6–1 Sample Record Description . ................................ 6–9

6–2 Determining Fixed-Length Record Size . ....................... 6–10

6–3 Determining Fixed-Length Record Size for Files with Multiple Record

Descriptions ............................................. 6–10

6–4 Creating Variable-Length Records with the DEPENDING ON

Phrase . ................................................ 6–11

6–5 Creating Variable-Length Records with the RECORD VARYING

Phrase . ................................................ 6–11

6–6 Creating Variable-Length Records and Using the OCCURS Clause

with the DEPENDING ON Phrase ........................... 6–11

6–7 Deﬁning Fixed-Length Records with Multiple Record Descriptions . . . 6–12

6–8 Deﬁning a Disk File ....................................... 6–15

6–9 Deﬁning a Magnetic Tape File (OpenVMS) ..................... 6–16

6–10 Deﬁning a Magnetic Tape File (Tru64 UNIX) ................... 6–16

6–11 Using Environment Variables for File Speciﬁcation ............... 6–19

6–12 Using Environment Variables ............................... 6–19

6–13 Specifying Sequential File Organization and Sequential Access Mode

for a Sequential File ...................................... 6–21

6–14 Specifying Relative File Organization and Random Access Mode for a

Relative File............................................. 6–21

6–15 Specifying Indexed File Organization and Dynamic Access Mode for

an Indexed File . . ........................................ 6–21

6–16 Specifying Line Sequential File Organization with Sequential Access

Mode . . ................................................ 6–22

6–17 SELECT Statements for Sequential Files with Sequential Access

Mode . . ................................................ 6–23

6–18 SELECT Statements for Relative Files with Sequential and Dynamic

Access Modes ............................................ 6–23

6–19 SELECT Statements for Indexed Files with Dynamic and Default

Sequential Access Modes . . . ................................ 6–24

6–20 SELECT Statements for Line Sequential Files with Sequential Access

Modes . ................................................ 6–24

6–21 OPEN and CLOSE Statements .............................. 6–25

6–22 Creating a Sequential File . . ................................ 6–26

6–23 Creating a Line Sequential File .............................. 6–27

6–24 Creating a Relative File in Sequential Access Mode .............. 6–30

6–25 Creating a Relative File in Random Access Mode . ............... 6–30

6–26 Creating and Populating an Indexed File ...................... 6–33

6–27 Using Segmented Keys .................................... 6–35

6–28 Reading a Sequential File . . ................................ 6–38

6–29 Reading a Relative File Sequentially . . . ....................... 6–39

6–30 Reading a Relative File Randomly............................ 6–40

6–31 Reading a Relative File Dynamically . . . ....................... 6–41

6–32 Reading an Indexed File Sequentially . . ....................... 6–42

6–33 Reading an Indexed File Randomly ........................... 6–43

6–34 Reading an Indexed File Dynamically . . ....................... 6–45

6–35 Reading an Indexed File Dynamically, with READ PRIOR . . ....... 6–46

6–36 Rewriting a Sequential File . ................................ 6–49

6–37 Extending a Sequential File ................................. 6–50

6–38 Rewriting Relative Records in Sequential Access Mode . ........... 6–51

6–39 Rewriting Relative Records in Random Access Mode . . . ........... 6–52

6–40 Deleting Relative Records in Sequential Access Mode . . ........... 6–53

6–41 Deleting Relative Records in Random Access Mode ............... 6–54

6–42 Updating an Indexed File Sequentially ........................ 6–56

6–43 Updating an Indexed File Randomly .......................... 6–57

7–1 Handling the AT END Condition . ............................ 7–2

7–2 Handling the Invalid Key Condition .......................... 7–3

7–3 Deﬁning a File Status for a File . ............................ 7–4

7–4 Using the File Status Value in an Exception Handling Routine . . . . . 7–4

7–5 Referencing RMS-STS, RMS-STV, RMS-CURRENT-STS, and

RMS-CURRENT-STV Codes (OpenVMS) . . . ................... 7–6

7–6 The Declaratives Skeleton .................................. 7–9

7–7 A Declarative USE Procedure Skeleton ........................ 7–9

7–8 Five Types of Declarative USE Procedures . . ................... 7–10

8–1 X/Open Standard Lock Modes and Opening Files ................ 8–7

8–2 Program Segment for File Status Values ....................... 8–13

8–3 Program Segment for RMS-STS Values (OpenVMS) . . . ........... 8–15

8–4 X/Open Standard Record Locking ............................ 8–18

8–5 Automatic Record Locking (Compaq Standard) .................. 8–19

8–6 Sample Program Using Manual Record Locking (Compaq

Standard) . . . ............................................ 8–21

8–7 Program Segment for Record-Locking Exceptions ................ 8–25

9–1 INPUT and OUTPUT PROCEDURE Phrases ................... 9–4

9–2 USING Phrase Replaces INPUT PROCEDURE Phrase . ........... 9–6

9–3 Overriding the COLLATING SEQUENCE IS Phrase. . . ........... 9–7

9–4 Using Two Sort Files . . .................................... 9–7

9–5 The Declarative USE AFTER STANDARD ERROR PROCEDURE . . 9–9

9–6 Using the MERGE Statement . . . ............................ 9–10

9–7 Sorting a File with the USING and GIVING Phrases . . ........... 9–11

9–8 Using the USING and OUTPUT PROCEDURE Phrases ........... 9–12

9–9 Using the INPUT PROCEDURE and OUTPUT PROCEDURE

Phrases ................................................ 9–14

9–10 Using the COLLATING SEQUENCE IS Phrase ................. 9–16

9–11 Creating a New Sort Key ................................... 9–17

9–12 Merging Files ............................................ 9–19

10–1 Components of a Report .................................... 10–2

10–2 Checking for the Page-Overﬂow Condition . . . ................... 10–8

10–3 Page Advancing and Line Skipping ........................... 10–9

10–4 Checking for End-of-Page on a 28-Line Logical Page . . . ........... 10–16

10–5 Programming a 20-Line Logical Page Deﬁned by the LINAGE Clause

with Automatic Page Overﬂow . . . ............................ 10–22

10–6 Sample Program EX1006 ................................... 10–45

10–7 Sample Program EX1007 ................................... 10–49

10–8 Sample Program EX1008 ................................... 10–58

10–9 Sample Program EX1009 ................................... 10–65

xvi

10–10 Sample Program EX1010 . . . ................................ 10–75

10–11 Printing Labels Four-Up . . . ................................ 10–83

10–12 Printing Labels Four-Up in Sort Order . ....................... 10–85

11–1 Erasing a Screen . ........................................ 11–5

11–2 Cursor Positioning ........................................ 11–6

11–3 Using PLUS for Cursor Positioning ........................... 11–8

11–4 Using Character Attributes . ................................ 11–9

11–5 Using the CONVERSION Phrase............................. 11–10

11–6 Using the ON EXCEPTION Phrase ........................... 11–13

11–7 Using the SIZE and PROTECTED Phrases ..................... 11–15

11–8 Using the NO ECHO Phrase ................................ 11–16

11–9 Using the DEFAULT Phrase ................................ 11–18

11–10 Using the CONTROL KEY IN Phrase . . ....................... 11–25

11–11 EDITING Phrase Sample Code .............................. 11–29

11–12 Designing a Video Form for a Daily Calendar ................... 11–36

12–1 Run Unit with Three Separately Compiled Programs ............. 12–2

12–2 Run Unit with a Main Program and Two Contained Programs ...... 12–3

12–3 Run Unit with Three Separately Compiled Programs, One with Two

Contained Programs ...................................... 12–4

12–4 Execution Sequence of Nested CALL Statements . ............... 12–6

12–5 Sequence of Messages Displayed When Example 12–4 Is Run ...... 12–8

12–6 Using the COMMON Clause ................................ 12–14

12–7 Calling a COBOL Program from C............................ 12–20

12–8 C Include File cobfunc.h.................................... 12–20

12–9 COBOL Called Program "CALLEDFROMC" .................... 12–21

12–10 C Program Using cobcall, cobfunc, and cobcancel. . ............... 12–22

12–11 COBOL Called Program "PROGCOB" . . ....................... 12–22

12–12 Calling a Fortran Program from a COBOL Program .............. 12–25

12–13 Fortran Subroutine SQROOT ................................ 12–26

12–14 Calling a BASIC Program from a COBOL Program ............... 12–27

12–15 BASIC Program "APP" and Output Data ....................... 12–28

12–16 C Routine to Be Called from a COBOL Program . . ............... 12–29

12–17 Calling a C Program from a COBOL Program ................... 12–29

13–1 User-Written Condition Handler ............................. 13–17

13–2 Random Number Generator (OpenVMS) ....................... 13–19

13–3 Using the SYS$SETDDIR System Service (OpenVMS) ............ 13–20

13–4 Using $ASCTIM (OpenVMS) ................................ 13–20

13–5 Sample Run of CALLTIME (OpenVMS) . ....................... 13–21

13–6 Using LIB$K_* and LIB$_* Symbols (OpenVMS) . ............... 13–22

16–1 Using *DC SET ALIGNMENT Directives ...................... 16–8

16–2 Using /ALIGNMENT with SYNCHRONIZED ................... 16–9

16–3 Comparing /NOALIGN, /ALIGN and /ALIGN=PADDING . . . ....... 16–10

16–4 Data Map for /NOALIGNMENT ............................. 16–11

16–5 Data Map for /ALIGNMENT, -align ........................... 16–11

16–6 Data Map for /ALIGNMENT=PADDING, -align pad .............. 16–12

B–1 Signed and Unsigned Differences ............................. B–18

B–2 Illegal Return Value Coding . ................................ B–19

xvii

C–1 Source Code Used in the Sample Debug Sessions ................ C–4

Figures

1–1 Commands for Developing Compaq COBOL Programs on Tru64

UNIX .................................................. 1–8

1–2 DCL Commands for Developing Programs . . . ................... 1–28

4–1 Organization of the One-Dimensional Table in Example 4–1 ........ 4–2

4–2 Organization of Multiple Data Items in a One-Dimensional Table. . . . 4–3

4–3 Organization of a Table with an Index and an Ascending Search

Key ................................................... 4–4

4–4 Organization of a Two-Dimensional Table . . . ................... 4–5

4–5 Organization of a Three-Dimensional Table . . ................... 4–5

4–6 Memory Map for Example 4–7 . . . ............................ 4–7

4–7 Memory Map for Example 4–8 . . . ............................ 4–8

4–8 Memory Map for Example 4–9 . . . ............................ 4–9

4–9 Memory Map for Example 4–10 . . ............................ 4–9

4–10 Memory Map for Example 4–11 . . ............................ 4–10

4–11 Memory Map for Example 4–13 . . ............................ 4–11

4–12 Memory Map for Example 4–14 . . ............................ 4–12

5–1 Results of the STRING Operation ............................ 5–3

5–2 Matching Delimiter Characters to Characters in a Field ........... 5–19

5–3 Sample INSPECT Statement ................................ 5–21

5–4 Typical REPLACING Phrase ................................ 5–22

5–5 The Replacement Argument ................................. 5–31

6–1 Sequential File Organization ................................ 6–3

6–2 A Multiple-Volume, Sequential File ........................... 6–4

6–3 Line Sequential File Organization ............................ 6–5

6–4 Relative File Organization .................................. 6–6

6–5 Indexed File Organization .................................. 6–8

8–1 Multiple Access to a File ................................... 8–1

8–2 Relationship of Record Locking to File Sharing .................. 8–2

8–3 Why a Record-Already-Exists Error Occurs . . ................... 8–16

10–1 Sample Layout Worksheet .................................. 10–2

10–2 Subtotals, Crossfoot Totals, and Rolled Forward Totals . ........... 10–5

10–3 Logical Page Area for a Conventional Report . ................... 10–6

10–4 A 20-Line Logical Page .................................... 10–11

10–5 A Double-Spaced Master Listing . ............................ 10–12

10–6 Logical Page Areas for a Linage-File Report . ................... 10–13

10–7 A 28-Line Logical Page .................................... 10–16

10–8 A 20-Line Logical Page .................................... 10–20

10–9 Presentation Order for a Logical Page ......................... 10–27

10–10 Sample Report Using All Seven Report Groups .................. 10–28

10–11 First GENERATE Statement ................................ 10–39

10–12 Subsequent GENERATE Statements .......................... 10–40

10–13 TERMINATE Statement ................................... 10–41

10–14 Sample MASTER.DAT File ................................. 10–44

xviii

10–15 EX1006.LIS Listing ....................................... 10–48

10–16 EX1007.LIS Listing ....................................... 10–56

10–17 EX1008.LIS Listing ....................................... 10–65

10–18 EX1009.LIS Listing ....................................... 10–73

10–19 EX1010.LIS Listing ....................................... 10–81

10–20 Printing Labels Four-Up . . . ................................ 10–83

10–21 Printing Labels Four-Up in Sort Order . ....................... 10–85

11–1 Adding Information to a Master File with a Video Form . . . ....... 11–4

11–2 Screen After the ERASE Statement Executes ................... 11–6

11–3 Positioning the Data on Line 19, Column 5 ..................... 11–7

11–4 Cursor Positioning Using the PLUS Option ..................... 11–8

11–5 Screen Display with Character Attributes ...................... 11–10

11–6 Sample Run of Program CONVERT ........................... 11–12

11–7 Accepting Data with the ON EXCEPTION Option. ............... 11–14

11–8 Screen Display of NUM-DATA Using the PROTECTED Option...... 11–16

11–9 Accepting Data with the DEFAULT Phrase ..................... 11–19

11–10 Compaq COBOL Control Keys on the Standard VT100 Keypad and

Keyboard ............................................... 11–24

11–11 Compaq COBOL Control Keys on a Typical VT200 or Later Keypad

and Keyboard . . . ........................................ 11–24

11–12 Screen Display of Program SPECIAL . . ....................... 11–28

11–13 Form with ACCEPT WITH EDITING Phrase ................... 11–31

11–14 MENU-SCREEN Output . . . ................................ 11–40

11–15 SCHEDULE-SCREEN Output ............................... 11–40

12–1 Nesting CALL Statements . ................................ 12–6

12–2 Transfer of Control Flow from a Main Program to Multiple

Subprograms ............................................ 12–9

12–3 Accessing Another Program’s Data Division..................... 12–10

12–4 Deﬁning Data Names in the Linkage Section ................... 12–13

12–5 Sharing USE Procedures . . . ................................ 12–16

12–6 Executing Declaratives with Contained Programs (Rule 1) . . ....... 12–17

12–7 Executing Declaratives Within Contained Programs (Rule 2) ....... 12–18

15–1 Sharing Record Areas ..................................... 15–14

15–2 Two-Level Primary Index . . . ................................ 15–19

Tables

1–1 Other File Name Sufﬁxes . . . ................................ 1–9

1–2 Compaq COBOL Command Flags on Tru64 UNIX. ............... 1–12

1–3 Main Tools for Program Development and Testing . ............... 1–26

1–4 COBOL Command Qualiﬁers ................................ 1–32

1–5 Commonly Used LINK Qualiﬁers ............................ 1–40

2–1 Numeric Relational Operator Descriptions ...................... 2–3

2–2 Sign Tests .............................................. 2–4

2–3 Numeric Editing . ........................................ 2–8

2–4 ROUNDING ............................................. 2–13

3–1 Relational Operator Descriptions ............................. 3–4

xix

3–2 Nonnumeric Elementary Moves . . ............................ 3–8

3–3 Data Movement with Editing Symbols ......................... 3–9

3–4 Data Movement with the JUSTIFIED Clause ................... 3–10

4–1 Subscripting Rules for a Multidimensional Table................. 4–14

4–2 Subscripting with Data Names . . ............................ 4–14

5–1 Results of Sample Overﬂow Statements ........................ 5–5

5–2 Values Moved into the Receiving Items Based on the Sending Item

Value .................................................. 5–7

5–3 Handling a Short Sending Item . . ............................ 5–8

5–4 Results of Delimiting with an Asterisk ........................ 5–9

5–5 Results of Delimiting Multiple Receiving Items .................. 5–10

5–6 Results of Delimiting with Two Asterisks . . . ................... 5–10

5–7 Results of Delimiting with ALL Asterisks . . . ................... 5–11

5–8 Results of Delimiting with ALL Double Asterisks ................ 5–11

5–9 Results of Multiple Delimiters . . . ............................ 5–12

5–10 Values Resulting from Implicit Redeﬁnition . . ................... 5–20

5–11 Relationship Among INSPECT Argument, Delimiter, Item Value, and

Argument Active Position .................................. 5–23

5–12 LEADING Delimiter of the Inspection Operation ................ 5–25

5–13 Results of the Scan with Separate Tallies . . . ................... 5–26

6–1 Compaq COBOL File Organizations—Advantages and

Disadvantages ........................................... 6–2

6–2 Record Format Availability ................................. 6–8

6–3 Valid I/O Statements for Sequential Files . . . ................... 6–27

6–4 Valid I/O Statements for Line Sequential Files .................. 6–28

6–5 Valid I/O Statements for Relative Files ........................ 6–32

6–6 Valid I/O Statements for Indexed Files ........................ 6–34

6–7 Indexed File—ISAM Mapping . . . ............................ 6–47

8–1 File-Sharing Options (OpenVMS) . ............................ 8–10

8–2 File-Sharing Options (Tru64 UNIX) ........................... 8–11

8–3 File Status Values Used in a File-Sharing Environment ........... 8–12

8–4 RMS-STS Values Used in a File-Sharing Environment (OpenVMS). . . 8–14

8–5 Manual Record Locking Combinations ......................... 8–20

10–1 Report Writer Report Group Types ........................... 10–26

10–2 Results of Group Indicating ................................. 10–87

11–1 Available Character Attributes by Terminal Type ................ 11–9

11–2 Compaq COBOL Characters Returned for Cursor Positioning,

Program Function, Function, Keypad, and Keyboard Keys ......... 11–20

11–3 Key Functions for the EDITING Phrase ....................... 11–28

11–4 Character Attribute Clauses for Screen Description Formats ....... 11–32

11–5 Color Table. . ............................................ 11–34

12–1 Calls to COBOL Programs .................................. 12–19

12–2 C Routine Called by Statement: CALL ‘‘Job1’’ ................... 12–31

12–3 C Invocation to Call COBOL PROGRAM-ID ‘‘Job2’’ ............... 12–31

13–1 OpenVMS Alpha Register Usage (OpenVMS) ................... 13–2

13–2 Run-Time Library Facilities (OpenVMS) ....................... 13–4

13–3 System Services (OpenVMS) ................................ 13–4

13–4 COBOL Implementation of the OpenVMS Alpha Data Types

(OpenVMS) ............................................. 13–8

16–1 Boundaries for Naturally Aligned Binary Data . . . ............... 16–4

16–2 Alignment and Padding Order of Precedence .................... 16–7

B–1 Cross-Platform Compatibility of COBOL Features . ............... B–1

B–2 Qualiﬁers Shared by Compaq COBOL and Compaq COBOL for

OpenVMS VAX and Equivalent Flags and Options ............... B–5

B–3 Compaq COBOL Options Not Available in Compaq COBOL for

OpenVMS VAX . . . ........................................ B–6

B–4 Compaq COBOL for OpenVMS VAX Speciﬁc Qualiﬁers ............ B–8

C–1 Oracle CDD/Repository Data Types ........................... C–21

D–1 Recognized Foreign Reserved Words . . . ....................... D–2

xxi

This manual provides information to help you develop Compaq COBOL programs for the OpenVMS Alpha and Compaq Tru64 UNIX platforms.

Compaq COBOL is the new name for DEC COBOL and for DIGITAL COBOL. Compaq COBOL, unmodiﬁed, refers to the COBOL language on three platforms:

OpenVMS Alpha Tru64 UNIX Windows NT Alpha (described in separate documentation)

Compaq COBOL for OpenVMS VAX is the new name for VAX COBOL and DIGITAL VAX COBOL. It is the COBOL implementation for the OpenVMS VAX platform. (It is described in a separate documentation set.)

Any references to the former names in product documentation or other components should be construed as references to the Compaq COBOL names.

All references in this manual to Windows NT mean Microsoft Windows NT Alpha.

Intended Audience

This manual is intended for experienced applications programmers who have a thorough understanding of the COBOL language. Some familiarity with your operating system is also recommended. This is not a tutorial manual.

Preface

If you are a new COBOL user, you may need to read introductory COBOL textbooks or take COBOL courses. Additional prerequisites are described at the beginning of each chapter or appendix, if appropriate.

Document Structure

This manual is organized as follows:

• Chapter 1 describes how to create, compile, link, and run Compaq COBOL programs and how to develop programs at the command level.

• Chapter 2 describes how the Compaq COBOL compiler stores, represents, moves, and manipulates numeric data.

• Chapter 3 describes how the Compaq COBOL compiler stores, represents, moves, and manipulates nonnumeric data.

• Chapter 4 describes how to deﬁne, initialize, and access tables.

• Chapter 5 describes how to perform text manipulation using the STRING, UNSTRING, and INSPECT statements.

• Chapter 6 describes I/O services provided by the operating systems, including record management services.

• Chapter 7 describes how to include exception handling routines in Compaq COBOL programs.

xxiii

• Chapter 8 describes ﬁle sharing and record locking for sequential, relative, and indexed ﬁles.

• Chapter 9 describes how to sort and merge ﬁles using the SORT and MERGE statements.

• Chapter 10 describes how to produce printed reports.

• Chapter 11 describes screen handling using the Compaq COBOL ACCEPT and DISPLAY statements.

• Chapter 12 describes how Compaq COBOL programs communicate with each other or with non-COBOL programs through the CALL statement and external data.

• Chapter 13 describes the use of Compaq COBOL in the OpenVMS Alpha Common Language Environment.

• Chapter 14 describes how to use the REFORMAT utility, which converts terminal format source programs to conventional ANSI format and converts conventional ANSI format source programs to terminal format.

• Chapter 15 presents guidelines for using the Compaq COBOL compiler optimization features.

• Chapter 16 describes how to use compile-time and run-time features to optimize the use of system resources while also maximizing run-time performance.

• Appendix A contains a list of Compaq COBOL speciﬁcatons and limits on the Tru64 UNIX and OpenVMS Alpha systems.

• Appendix B describes compatibility and portability issues between Compaq COBOL for OpenVMS VAX and Compaq COBOL on the Tru64 UNIX and OpenVMS Alpha systems.

• Appendix C describes optional programming productivity tools available on OpenVMS Alpha systems and Tru64 UNIX systems.

• Appendix D describes porting assistance for migrating applications between other COBOL compilers and Compaq COBOL.

• The Index indexes and references terms in this manual.

Associated Documents

The following documents contain additional information directly related to various topics in this manual:

Compaq COBOL Reference Manual

This manual describes the concepts and rules of the Compaq COBOL programming language under the supported operating systems.

Release Notes

Consult the Compaq COBOL release notes for your installed version for late corrections and new features.

xxiv

On the OpenVMS Alpha operating system, the release notes are in:

SYS$HELP:COBOLnnn.RELEASE_NOTES (ASCII text) SYS$HELP:COBOLnnn_RELEASE_NOTES.PS

where nnn is the version and release number, for example, 027 for Version

2.7.

On the Tru64 UNIX operating system, the release notes are in:

/usr/lib/cmplrs/cobol/relnotes

Compaq COBOL Installation Guide for OpenVMS Alpha Systems

This manual provides information on how to install Compaq COBOL on the

Convention Meaning

Braces used in a general format enclose lists from which you must choose only one item. For example:

(

SEQUENTIAL RANDOM DYNAMIC

)

Brackets used in a general format enclose optional items from which you can choose none or one. For example:



RECORD



ALL RECORDS









. . . A horizontal ellipsis indicates that the item preceding the

. . .

Format Program examples are shown in terminal format, rather than

special-character words The following symbols, when used in a general format,

Choice indicators, vertical lines inside a set of braces, used in a general format enclose lists from which you must choose one or more items, using each item chosen only once. For example:



  

;

...



COMMON

 

INITIAL

ellipsis can be repeated. For example:

switch-name

A vertical ellipsis indicates that not all of the statements are shown.

in ANSI standard format.

constitute required special-character words:

xxvi

Plus sign (+) Minus sign (-) Single (=) and double ( = = ) equal signs Less than (<) or greater than (>) symbols Less than or equal to (<=) and greater than or equal to (>=) symbols Period (.) Colon ( : ) Single (*) and double ( ** ) asterisks Slash ( / ) Left parenthesis (( ) or right parenthesis ())

quotation mark The term quotation mark is used to refer to the double

apostrophe The term apostrophe is used to refer to the single quotation

user input

quotation mark character (").

mark character (’ ). In examples, user input (what you enter) is shown as

monospaced text

Convention Meaning

extensions Compaq extensions to the 1985 ANSI COBOL Standard are

report ﬁle Bold type indicates a new term. full-ﬁle-name This syntax term refers to the name of a ﬁle and the device

color coded in blue or gray. Note that the term extension in this manual means a Compaq extension to the ANSI COBOL Standard. (Some of these extensions are included in the X/Open CAE Standard for the COBOL language.)

and directory, or path, in which it is located. For example:

c:\home\public\filename.txt (Windows NT path) DISK2$:[HOME.PUBLIC]FILENAME.TXT; (OpenVMS file

specification) /disk2/home/public/filename.txt (Tru64 UNIX

file specification)

compiler option This term refers to command-line qualiﬁers (OpenVMS Alpha

systems), options (Windows NT Alpha systems), or ﬂags (Tru64 UNIX systems). For example:

/LIST (OpenVMS qualifier or NT option)†

-list (Tru64 UNIX flag or NT option)†

COBOL This term refers to language information common to ANSI-85

Return

Tab Ctrl/x

$ The dollar sign ($) represents the OpenVMS system prompt. % The percent sign (%) represents the Tru64 UNIX system

C:\> A letter followed by a colon (: ), a backslash \, and a greater-

Start| Programs | . . . A series of names separated by vertical bars ( | ) means you

COBOL, Compaq COBOL, and Compaq COBOL for OpenVMS VAX.

A boxed symbol indicates that you must press a key on the terminal; for example, Return key.

This symbol indicates a nonprinting tab character. The symbol

CTRL while you press another key, for example,

prompt.

than sign (>) represents the MS-DOS system prompt.

should click on the ﬁrst named Windows NT object, then the second named object, and so on.

Ctrl/x

Return

indicates that you press the

indicates that you hold down the key labeled

Ctrl CorCtrl O

References

†Either the slash or the hyphen is acceptable for Windows NT compiler options. Use the slash for Windows NT linker options.

The following table shows certain references and their respective meanings in this manual:

Reference Meaning

OpenVMS OpenVMS Alpha operating system Tru64 UNIX Compaq Tru64 UNIX operating system Windows NT Microsoft Windows NT Version 4.0, SP4, SP5 for Alpha systems

xxvii

Compaq Tru64 UNIX was formerly known as DEC OSF/1 or as DIGITAL UNIX. Compaq COBOL was formerly known as DIGITAL COBOL or DEC COBOL. Compaq COBOL for OpenVMS VAX was formerly known as VAX COBOL or as DIGITAL VAX COBOL.

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

The authors and copyright holders of the copyrighted material used herein are as follows: FLOW-MATIC (trademark of Unisys Corporation), Programming for the UNIVAC (R) I and II, Data Automation Systems, copyrighted 1958, 1959, by Unisys Corporation; IBM Commercial Translator Form No. F28-8013, copyrighted 1959 by IBM; FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell.

They have speciﬁcally authorized the use of this material, in whole or in part, in the COBOL speciﬁcations. Such authorization extends to the reproduction and use of COBOL speciﬁcations in programming manuals or similar publications.

How to Order Additional Documentation

For information on pricing and where to buy documentation and other Compaq products in the United States and Canada, please call toll-free 1-800-282-6672.

Reader’s Comments

Compaq appreciates your comments. If you ﬁnd errors or want to comment about this manual, please send the manual title, order number, and your comments by one of the following methods:

• Electronic Internet mail:

LanguageDocs@compaq.com

• Fax:

603–884–0120 Attn: Languages Documentation, ZKO2–3/K35

• A letter sent to the following address:

Compaq Computer Corporation Languages Documentation, ZKO2–3/K35 110 Spit Brook Road Nashua, NH 03062–2698 USA

xxviii

User Programs and the Year 2000

Even subsequent to the turn of the century, there still exist potential disruptions in previously problem-free software where there are instances of a two-digit year ﬁeld that should be a four-digit ﬁeld. Programmers need to correct all such ﬁelds, as Compaq cannot prevent problems that originate in application code.

For more information, see Section 1.6.

New Features

Consult the Index for entries under Version 2.7 – what’s new since V2.5. They will point you to information added since Version 2.5 of Compaq COBOL.

xxix

Developing Compaq COBOL Programs

Compaq COBOL is a powerful optimizing compiler produced by Compaq Computer Corporation. It operates comfortably in the Compaq common language environment; it is based on GEM, which is the highly advanced code generator and optimizer that Compaq uses in its family of languages, which includes COBOL, C, C++, FORTRAN 77, FORTRAN 90, BASIC, Ada, and PASCAL. In addition to standard COBOL features, Compaq COBOL includes extensions that make new application development efﬁcient and effective, with features helpful in porting legacy COBOL programs to OpenVMS Alpha and Tru64 UNIX systems.

Developing software applications with Compaq COBOL will be a familiar process. You set up your development environment, create your source, compile, link, and run. A few of the speciﬁc tasks are:

• Choosing a reference format: terminal or ANSI

• Carefully considering Alpha architecture system resources; for example, you might invest more system resources at compile time to get faster execution at run time

• Using various system-independent features for program development

1.0.1 Files Installed on Your System

You will have the following directories and ﬁles added to your system after a typical installation:

(drive letter):\DEC\COBOL\Vnn

where nn shows the version and release numbers. For example, for Version 2.7 nn is 27.

COBOL_ENV.BAT COBOL_IVP.BAT DeIsL1.isu \Acrobat31 \BIN \DOCS \DOCS_HTML \FX32 \ICD \LIB \MS_Tools \XICD

\Client_Server

\Examples

\IVP \Reformat

Developing Compaq COBOL Programs 1–1

Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

For many user applications, the Compaq COBOL compiler requires signiﬁcantly more system resources than Compaq COBOL for OpenVMS VAX. In fact, unless you have adjusted your system resource parameters accordingly, the attempt to compile may fail because of insufﬁcient virtual memory. Also, for very large programs (greater than 10,000 lines), you might experience extremely long compile times. Knowing why Compaq COBOL requires more memory can help you take actions to avoid resource problems.

1.1.1 Compilation Performance

The Alpha architecture is a RISC (reduced instruction set computer) architecture. Many other processor architectures, including the VAX, are CISC (complex instruction set computer) architectures. The main distinguishing characteristic of a RISC machine is that it has few instructions and each instruction does a small amount of work. A CISC machine generally has many instructions, most of which perform many complicated operations in one step.

By reducing the amount of work that is done in each instruction (and by reducing the number of instructions), the complexity of the hardware is reduced. These hardware changes, plus others, result in an increase in the number of instructions per second that can be completed. The result is much faster overall system performance.

A tradeoff of RISC systems is that compilers for these architectures generally must do a great deal more work than a corresponding compiler for a CISC architecture. For example, the compiler must compute the best way to use all of the functional units of the processor, and it must determine how to make the best use of registers and on-chip data cache because reads and writes to main memory are generally slow compared to the speed of the processor.

The code generation portion of the Compaq COBOL for OpenVMS VAX compiler examines one COBOL statement at a time, determines the VAX instructions to be constructed to execute that statement, and then moves on to the next one. This tactic works well for a CISC architecture like the VAX. Compaq COBOL for OpenVMS VAX does ‘‘peephole’’ optimization.

The Compaq COBOL compiler, in contrast, is a globally optimizing compiler based on the Alpha RISC architecture as well as mathematical concepts. The compiler constructs an internal representation of the entire COBOL program, and repeatedly traverses this structure at compile time, so that it can produce the most efﬁcient machine code for the program. This results in very high performance code, to the beneﬁt of your users at run time. Although the Compaq COBOL compiler requires more resources than some other compilers to do this additional work at compile time, this cost is offset by better performance during the many run times that follow.

To reduce this impact on system resources, do the following:

-O0

• Use /NOOPTIMIZE or developing and testing programs. The optimizer is one of the heaviest users of system resources in the COBOL compiler and is turned on by default. Also, the higher the optimization level, the more memory required by the compiler.

on the compile command line when initially

• Check system tuning. Because the Compaq COBOL compiler often needs a great deal of virtual memory, you may need to increase virtual memory for developers who use the compiler. This results in decreased paging and improvements in compile time.

1–2 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

• Check program sizes. Larger amounts of system resources are used during compilation for large monolithic source ﬁles. It is possible that your application is already composed of several separately compiled program units (different PROGRAM IDs not nested), but all in the same .COB. On Alpha systems with Compaq COBOL, compilation performance improves if you split the program units into separate (smaller) .COB ﬁles (possibly one for each separately compiled program unit).

Note

Large arrays (tables) can have a signiﬁcant impact on compile time and resource requirements. In addition to the size of the program source, you should also examine the amount of space allocated in your Data Division, particularly for arrays. The number of array elements as well as the size of the array elements is signiﬁcant. This impact can be minimized in two ways: by system tuning (as suggested in this section), which will optimize system resources for the compile, and by using INITIALIZE instead of VALUE in your data deﬁnitions, which will improve compilation performance.

1.1.2 Tuning OpenVMS Alpha for Large Compaq COBOL Compiles

The recommendations that follow were determined by compiling one set of very large Compaq COBOL modules on OpenVMS Alpha. While your results may vary, the principles are generally applicable. For more detailed information on OpenVMS Alpha tuning, see the OpenVMS System Manager’s Manual, particularly the sections on Managing System Parameters and Managing System Page, Swap, and Dump Files.

Note that many tuning exercises are more beneﬁcial if you work with a relatively quiet system, submit batch jobs, and retain the log ﬁles for later analysis.

1.1.2.1 Optimizing Virtual Memory Usage

If your system does not have enough virtual memory allocated, the compile may fail, with the ‘‘%LIB-E-INSVIRMEM, insufﬁcient virtual memory’’ error reported.

OpenVMS has two parameters that control the amount of virtual memory available to a process. One is the system generation parameter VIRTUALPAGECNT, which sets an upper bound on the number of pagelets of virtual memory for any process in the system. The other control is the AUTHORIZE parameter PGFLQUOTA, which determines the number of pagelets a process can reserve in the system’s page ﬁle(s).

After an ‘‘insufﬁcient virtual memory’’ error, you can issue the DCL command $SHOW PROCESS/ACCOUNTING to see the ‘‘Peak virtual size’’ used by the process (or look at the ‘‘Peak page ﬁle size’’ at the end of a batch job log ﬁle). If the peak size is at the system generation parameter VIRTUALPAGECNT, you will need to raise this value. If the peak size is below VIRTUALPAGECNT, and at or above PGFLQUOTA, run AUTHORIZE to increase PGFLQUOTA for the COBOL users. (Peak size can exceed PGFLQUOTA because some virtual memory, such as read-only image code, is not allocated page ﬁle space.)

It is difﬁcult to predict precisely how much virtual memory will be required for a compilation, but a starting point for system tuning may be computed by multiplying 250 times the size of the largest program in disk blocks (including all

Developing Compaq COBOL Programs 1–3

Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

COPY ﬁles referenced). Alternatively, multiply 25 times the number of lines in the program (including all COPY ﬁles).

The resulting ﬁgure can then be used as a starting point for the system generation parameter VIRTUALPAGECNT. Put that ﬁgure in the parameter ﬁle SYS$SYSTEM:MODPARAMS.DAT. For example, if you estimate 370,000 pages, add the line following line in MODPARAMS, run AUTOGEN and reboot:

MIN_VIRTUALPAGECNT = 400000

If the compilation now completes successfully, use the command $SHOW PROCESS/ACCOUNTING to determine the Peak Virtual Size; if the actual peak is signiﬁcantly less than the value computed above, you can reduce VIRTUALPAGECNT.

When modifying VIRTUALPAGECNT and PGFLQUOTA, you may also need to increase the size of the page ﬁle.

1.1.2.2 Optimizing Physical Memory Usage

In any evaluation of your system’s physical memory, two of the questions to consider are:

Is there enough memory on the system? Is enough available to the process running the compilation?

More speciﬁcally:

• If the physical memory on the system is too small, the command $LOGOUT/FULL (which is automatically issued at the end of a batch job) will show a high number of faults (>100,000 for a single compilation) and an elapsed time value that greatly exceeds the Charged CPU time value, as the system waits for disk I/Os to resolve page faults. In this situation, tuning attempts may be of limited beneﬁt.

• If the physical memory on the system is adequate, but the physical memory allotted to the process running the compilation is too small, you may still observe a large number of faults, but elapsed time may remain closer to CPU time. This is because OpenVMS Alpha resolves page faults from the page caches (free list, modiﬁed list) whenever possible, avoiding the relatively slow disk I/Os. In this situation, basic tuning may also be beneﬁcial.

The amount of physical memory required will vary, but it should be a large percentage of the process peak virtual size—as close to 100% as practical. The reason is that the compiler makes multiple passes over the internal representation of the program. A page that falls out of the working set in one pass is probably going to be needed again on the very next pass.

The physical memory present on the system can be determined by the DCL command $SHOW MEMORY/PHYSICAL. The physical memory used by the compilation is reported as ‘‘Peak working set size’’ by the command SHOW PROCESS/ACCOUNTING or at the end of a batch log ﬁle.

More physical memory can be made available to a process by minimizing the number of competing processes on the system (for example, by compiling one module at a time or by scheduling large compiles for off-peak time periods; late at night is a good time in some situations).

1–4 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

More physical memory can also be made available to a process (if it is present on the machine) by adjusting the system generation parameter WSMAX and the corresponding WSEXTENT (in AUTHORIZE). Approach such adjustments with great caution, as the system may hang if memory is oversubscribed and you create a situation where OpenVMS Alpha effectively has no options to reclaim memory. The following guidelines can help:

• Set the COBOL user WSEXTENT (in AUTHORIZE or INITIALIZE/QUEUE) to match WSMAX.

• Keep WSQUOTA (in AUTHORIZE or INITIALIZE/QUEUE) low. Make sure that no process or batch queue has a WSQUOTA of more than approximately 20% of physical memory. The difference between WSEXTENT and WSQUOTA allows OpenVMS Alpha to manage memory to meet varying demands.

• Use AUTOGEN. AUTOGEN will attempt to make a consistent set of changes that do not interfere with each other.

By default, AUTOGEN will set the maximum working set (system generation parameter WSMAX) to 25% of physical memory. This value is reasonable for a workstation or multi-user system with many active processes.

WSMAX can be increased to a somewhat larger value by editing MODPARAMS.DAT. For a system with 64 MB WSMAX to no more than approximately 40% of physical memory, or 52000 pagelets (1 MB = 2048 pagelets). With 128 MB or more of physical memory, a setting of 50% of physical memory can be attempted.

of physical memory, set

The effects of physical memory on compilation time were studied for a set of seven large modules. These modules ranged in size from approximately 1600 to 3300 disk blocks. Your results may differ, but to give a rough appreciation for the effect of physical memory on compilation time, note that:

• When the amount of physical memory available to the processes matched the amount of virtual memory, the elapsed times were close to the CPU times.

• As the physical memory was reduced, CPU times rose only slightly— approximately 10%.

• As the physical memory was reduced, elapsed times were elongated, at the rate of approximately 1 hour for each 100 MB of difference between Peak Virtual Size and the actual memory available. For example, when compiling a program that used a Peak Virtual Size of 947760 pagelets, or 463 MB, on a system where approximately 180 MB of physical memory was available to user processes, the compile required approximately 3 hours more than on a 512 MB system.

Your results may differ from those shown in this section and will be strongly affected by the speed of the devices that are used for paging.

Note that the requirements for virtual memory and physical memory can also be reduced by breaking large modules into smaller modules.

MB= megabytes

Developing Compaq COBOL Programs 1–5

Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

1.1.2.3 Improving Compile Performance with Separate Compilation (OpenVMS)

The /SEPARATE_COMPILATION qualiﬁer can improve compile-time performance for large source ﬁles that are made up of multiple separately compiled programs (SCPs). For programs compiled without this qualiﬁer, the compiler engine parses the entire compilation unit and uses system resources (sized for the total job) for the duration of this compilation. When you use the /SEPARATE_COMPILATION qualiﬁer, the compilation is replaced by a smaller series of operations, and memory structures that are needed for individual procedures are reclaimed and recycled. See Section 1.3.2.4 for additional information. ♦

1.1.3 Choosing a Reference Format

You need to choose a reference format before you set out to write a Compaq COBOL program, and you must be aware of the format at compile time. The Compaq COBOL compiler accepts source code written in either terminal or ANSI reference format. You cannot mix reference formats in the same source ﬁle.

On OpenVMS, when copying text from Oracle CDD/Repository, the Compaq COBOL compiler translates the record descriptions into the reference format of the source program. ♦

1.1.3.1 Terminal Reference Format

Compaq recommends using terminal format, a Compaq optional format, when you create source ﬁles from interactive terminals. The compiler accepts terminal format as the default reference format.

Terminal format eliminates the line number and identiﬁcation ﬁelds of ANSI format and allows horizontal tab characters and short lines. Terminal format saves disk space and decreases compile time. It is easier to edit source code written in terminal format.

The following table shows the structure and content of a terminal reference source line:

Character Positions Contents

1 to 4 Area A 5 to 256 Area B End of line Margin R

You can use the Tab key or the space bar to position source entries in a line. Pressing the Return key signiﬁes the end of a line. Terminal format treats the end of each line as Margin R. Use a continuation (-) character when you want to continue a line. (This is useful for a quoted literal that is too long for one line.) If you wish to use a hyphen or continuation dash (-), a comment asterisk (*), or a skip-to-top-of-page slash (/) character, it must be placed in column 1. If you wish to use conditional compilation characters, they must be placed in columns 1 and

2. For more information about using conditional compilation characters and the Tab key, see the Compaq COBOL Reference Manual.

1–6 Developing Compaq COBOL Programs

1.1 Compaq COBOL and Alpha Architecture System Resources

1.1.3.2 ANSI Reference Format

ANSI format is useful on a card-oriented system or in an application where strict ANSI compliance is desired. To select ANSI format, specify the (on Tru64 UNIX systems) or the /ANSI_FORMAT qualiﬁer (on OpenVMS Alpha systems) at compile time. You can choose this format if your COBOL program is written for a compiler that uses ANSI format.

For ANSI format, the compiler expects 80-character program lines. The following table shows the structure and content of an ANSI reference source line:

Character Positions Contents

1 to 6 Optional sequence numbers 7 Indicators 8 to 11 Area A 12 to 72 Area B 73 to 80 Optional Area

For more information about the two reference formats, see the Compaq COBOL Reference Manual.

Developing Compaq COBOL Programs

-ansi

ﬂag

1.1.3.3 Converting Between Reference Formats

The REFORMAT utility allows you to convert a terminal format program to ANSI format and vice versa. You can also use REFORMAT to match the formats of Compaq COBOL source ﬁles and library ﬁles when their formats are not the same. See Chapter 14 for a description of the REFORMAT utility.

1.2 Developing Programs on Tru64 UNIX

This section brieﬂy describes the Tru64 UNIX commands (commands used at the operating system prompt) that you use to create, compile, link, and run Compaq COBOL programs on Tru64 UNIX systems.

1.2.1 Creating a Compaq COBOL Program on Tru64 UNIX

Use a text editor, such asvior instance, to edit the ﬁle

% vi prog1.cob

Figure 1–1 shows the basic steps in Compaq COBOL program development on Tru64 UNIX systems.

When naming a source ﬁle, choose one of the four ﬁle name extensions that the

cobol

compiler recognizes as COBOL ﬁle sufﬁxes. These sufﬁxes are:

prog1.cob

emacs

, to create and revise your source ﬁles. For

using thevieditor, type:

Developing Compaq COBOL Programs 1–7

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Figure 1–1 Commands for Developing Compaq COBOL Programs on Tru64

UNIX

COMMANDS

% vi prog1.cob Use the file type of cob

to indicate the file contains a Compaq COBOL program.

% cobol -c prog1.cob The cobol command

assumes file type. (If you use the -list flag,

the compiler creates a listing file; if you use the

-c flag, the compiler creates an object file.)

% cobol prog1.o

The link command assumes file type.no

% a.out

Type the output file name to run the image.

ACTION

Create a

source program

Compile the

source program

Link the

object module

Run the

executable

image

INPUT/OUTPUT FILES

prog1.cob

(prog1.o,

prog1.lis)

libraries

a.out

Note: case of file names is significant.

VM-0610A-AI

1–8 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

.cob .COB .cbl .CBL

Table 1–1 shows other ﬁle name sufﬁxes.

Table 1–1 Other File Name Sufﬁxes

Sufﬁx Description

.o .a

.so

The following automatically uses the linkerldto link the main program into an executable program ﬁle named

% cobol prog1.cob

The and Compaq COBOL libraries to the program reside in these standard libraries, additional libraries or object ﬁles are not speciﬁed on the

If your path deﬁnition includes the directory containing program by simply typing its name:

Identiﬁes C language ﬁles passed to the C compiler drivercc, which performs additional command line parsing before invoking the C language compiler.

Identiﬁes assembler ﬁles passed tocc. Compaq COBOL does not generate .s ﬁles.

Identiﬁes object ﬁles passed tocc, which are in turn passed told. Identiﬁes archive object libraries passed tocc, which are in turn passed told.

All routines in the speciﬁed object library will be searched during linking to resolve external references. This is one method of specifying special libraries for which the

Identiﬁes shared object libraries passed tocc, which are in turn passed told. All routines in the speciﬁed object library will be searched during linking to resolve external references. This is one method of specifying special libraries for which the

cobol

command automatically passes a standard default list of Tru64 UNIX

cobol

command compiles the program named

a.out

cobol

command does not automatically search.

(the name used if you do not specify a name):

linker. If all external routines used by a

command line.

a.out

prog1.cob

, you can run the

and

% a.out

If the executable image is not in your current directory path, specify the directory path in addition to the ﬁle name.

The COPY Statement and Libraries

As you write a program, you can use the COPY statement in your source program to include text from another ﬁle. With the COPY statement, separate programs can share common source text kept in libraries, reducing development and testing time as well as storage. The Compaq COBOL Reference Manual explains how to use the COPY statement.

Special Considerations for Routines Named ‘‘main’’

If you have a program or routine named ‘‘main,’’ declared either in a Compaq COBOL or other module, your application may not work correctly. The Compaq COBOL library contains a routine named ‘‘main,’’ which initializes the run-time environment for the CALL by data name statements, extended ACCEPT and DISPLAY statements, and some error handling. When your application also declares a ‘‘main,’’ your routine preempts the Compaq COBOL routine, and the run-time initialization is not performed.

Developing Compaq COBOL Programs 1–9

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Compaq recommends that you not name a Compaq COBOL program ‘‘main.’’ If you have a C routine named ‘‘main,’’ you can work around this problem by

having the ‘‘main’’ routine directly call the Compaq COBOL initialization routine, cob_init. The cob_init routine interface (in C) is as follows:

void cob_init ( /* init the RTL */

int argc, /* argument count */ char **argv, /* arguments */ char **envp /* environment variable pointers */ )

1.2.2 Compiling a Compaq COBOL Program on Tru64 UNIX

Compilation does the following for you:

• Detects errors in your program syntax

• Displays compiler messages on your terminal screen

• Generates machine language instructions from valid source statements

• Groups the instructions into an object module for the linker To compile your program, use the

The COBOL Command Driver

The

cobol

the Compaq COBOL compiler. It accepts a list of command ﬂags and ﬁle names and causes one or more processors (compiler, assembler, or linker) to process each ﬁle.

After the Compaq COBOL compiler processes the appropriate ﬁles to create

command invokes a compiler driver that is the actual user interface to

cobol

command.

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

An example

% cobol -v test.cob pas.o

This command speciﬁes the following:

• The-vﬂag displays the compilation and link passes with their arguments and ﬁles, including the libraries passed told.

• The ﬁle The resulting object ﬁle is then linked.

• The object ﬁle

As an additional example, you might ﬁnd that your compiler command lines are getting rather long, as shown in the following example:

% cobol -rsv foreign_extensions -flagger high_fips -warn information zeroes.cob

To work around this, you may truncate compiler ﬂag options (arguments) to their shortest unambiguous form, as follows:

% cobol -rsv for -flagger high -warn info zeroes.cob

1.2.2.2 COBOL Command Flags

Flags to the simplest form of the

If you compile parts of your program (compilation units) using multiple commands, ﬂags that affect the execution of the program should be used consistently for all compilations, especially if data will be shared or passed between procedures.

cobol

test.cob

cobol

command line would be:

is passed to the Compaq COBOL compiler for compilation.

pas.o

is passed directly to the linker.

command affect how the compiler processes a ﬁle. The

cobol

command is often sufﬁcient.

cobol

For a complete list of Compaq COBOL ﬂags, see Table 1–2. For more information about the Compaq COBOL ﬂags, access the reference (man) page for COBOL at the Tru64 UNIX system prompt. For example:

% man cobol

Developing Compaq COBOL Programs 1–11

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Table 1–2 Compaq COBOL Command Flags on Tru64 UNIX

Flag Default

-align [padding]

-ansi

off off

-arch -arch generic

-arithmetic native -arithmetic native

-arithmetic standard -arithmetic native

-C

-c

-call_shared

-check all

off on on off

-check [no]bounds -check nobounds

-check [no]decimal -check nodecimal

-check [no]perform -check noperform

-check none

-conditionals [selector]

on off

-convert [no]leading_blanks -convert noleading_blanks

-copy

-copy_list

-cord

-cross_reference

-cross_reference alphabetical

-cross_reference declared

-D num

-display_formatted

-feedback file

-fips 74

-flagger [option]

-granularity byte

-granularity long

, ,

off off off off off off off off off off off

-granularity quad

-g0

-g1

-g2or-g

-g3

-include

-K

-L

-Ldir

-list

-lstring

off on off off off off off off off off

1–12 Developing Compaq COBOL Programs

(continued on next page)

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Table 1–2 (Cont.) Compaq COBOL Command Flags on Tru64 UNIX

Flag Default

-machor-machine_code

-map

-map alphabetical

-map declared

-math_intermediate cit3

-math_intermediate cit4

, ,

-math_intermediate float

-names as_is

-names lower

-names lowercase

-names upper

, ,

-names uppercase

-nationality japan

-nationality us

-nolocking

-noobject

-non_shared -call_shared

-nowarn

-O0

-O1

-O2

-O3

-O4or-O

-o output

-p0

-p1or-p

-relax_key_checkingor-rkc

-rsv [no]200x -rsv no200x

-rsv [no]foreign_extensions -rsv noforeign_extensions

-rsv [no]xopen -rsv xopen

-seq

-sequence_check

-shared -call_shared

-show code

-show copy

-show xref

-stdor-std 85

-std [no]mia -std nomia

-std [no]syntax -std nosyntax

-std [no]v3 -std nov3

-std [no]xopen -std xopen

off off off off

-math_intermediate float

-names lowercase

-nationality us

off off

off off off off off on a.out on off off

off

off off off on

(continued on next page)

Developing Compaq COBOL Programs 1–13

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Table 1–2 (Cont.) Compaq COBOL Command Flags on Tru64 UNIX

Flag Default

-T num

-taso

-tps

-trunc

-tune -tune generic

-V

-v

-w

-warn -warn other

-warn all

-warn [no]information -warn noinformation

-warn [no]other -warn other

-warn none

-xref, -xref_stdout

off off off off

off off off

off

off off

Technical Notes:

1. If your program compile generates Errors (E-level diagnostics on OpenVMS Alpha), the link phase of the two steps taken by the compiler driver will be aborted and the object ﬁle(s) deleted. You can override this deletion by specifying the-cﬂag:

% cobol -c test.cob % cobol test.o

The Compaq COBOL compiler driver (see Section 1.2.2) controls a sequence of operations (as required): compiling, assembling, linking. The-cﬂag signals the compiler driver to break the sequence.

(For additional information, see The COBOL Command Driver description (earlier in this chapter), Section 1.2.2.12, and the-cdescription under

cobol

2. The

3. The

-tps

ﬂag causes the Compaq COBOL compiler to use an external ﬁle handler (produced by a third party), providing increased ﬂexibility in cross platform, transaction processing application development. See Section 1.2.2.3 for more information.

-xref

to generate a data ﬁle that the Compaq FUSE Database Manager uses to create a static analysis database ﬁle. This improves the performance of the Compaq FUSE Call Graph Browser and the Compaq FUSE Cross-Referencer, which use the database ﬁle for their operations. See the Compaq FUSE documentation for more information on the Compaq FUSE static analysis database, the Compaq FUSE Cross-Referencer and Compaq FUSE Call Graph Browser.

Specifying the ﬁle to standard output.

and

-xref_stdout

ﬂags direct the Compaq COBOL compiler

option directs the compiler to output the data

man

1–14 Developing Compaq COBOL Programs

4. Any copy ﬁle that contains a PROGRAM-ID or END PROGRAM statement for a program must contain that entire program. When compiled in the Compaq FUSE environment (using the compiler options certain Compaq COBOL programs may fail, with this fatal diagnostic result:

cobol: Severe: Fatal error -7 returned from a cross-referencing library procedure

To avoid this error, programmers should ensure that any subroutine beginning in a given ﬁle ends in the same ﬁle.

1.2.2.3 External File Handler Support

The

-tps

ﬂag allows Compaq COBOL applications to make use of ACMSxp, the

Application Control and Management System/Cross-Platform Edition.

-tps

speciﬁes that ﬁles are part of a transaction processing system, and enables Encina Structured File System (SFS) record storage for applicable ﬁles. It is intended to be used in conjunction with the Transarc Encina external ﬁle handler and ACMSxp, allowing access to data in a wide variety of databases, without the need to write code in the language of the databases. This approach provides access to transaction processing technology, and incorporates industry standards for data communications and distributed computing. ACMSxp conforms to the the Multivendor Integration Architecture (MIA).

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

-xrefor-xref_stdout

COBOL is one of the languages approved by MIA for transaction processing (TP) client programs, customer-written presentation procedures, and processing procedures. For database access, Structured Query Language (SQL) is the MIA-required access language. The SQL is embedded in COBOL and C.

See the ACMSxp documentation for full details. Additional information can also be found in published Distributed Computing Environment (DCE) documentation.

1.2.2.4 Specifying Multiple Files and Flags

The

cobol

ﬁle names are delimited by spaces. If appropriate, each ﬁle name can have a different sufﬁx. The ﬁle name sufﬁx could result in the following actions:

• Calling another language compiler, such as the C compiler

• Passing object ﬁles directly to the linker, which the linker combines with

other object ﬁles

• Passing an object library to the linker, which the linker uses to search for

unresolved global references

When a ﬁle is not in your current working directory, specify the directory path before the ﬁle name.

1.2.2.5 Compiling Multiple Files

An entire set of source ﬁles can be compiled and linked together using a single

cobol

command can specify multiple ﬁle names and multiple ﬂags. Multiple

command:

% cobol -o calc mainprog.cob array_calc.cob calc_aver.cob

This

cobol

command:

• Uses the-oﬂag to specify the name of the executable program as

• Compiles the ﬁle

array_calc.cob calc_aver.cob

Developing Compaq COBOL Programs 1–15

calc

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

• Compiles the ﬁle

• Usesldto link both the main program and object ﬁles into an executable program ﬁle named

The ﬁles can also be compiled separately, as follows:

% cobol -c array_calc.cob % cobol -c calc_aver.cob % cobol -o calc mainprog.cob array_calc.o calc_aver.o

In this case, the-coption prevents linking and retains the.oﬁles. The ﬁrst command creates the ﬁle

calc_aver.o

ﬁles into the executable program named If your path deﬁnition includes the directory containing

program by simply typing its name:

% calc

You can compile multiple source ﬁles by concatenating them:

% cat proga1.cob proga2.cob proga3.cob > com1.cob % cat progb1.cob progb2.cob > com2.cob % cobol -c com1.cob com2.cob

The resulting ﬁle names are com1.o and com2.o. The OpenVMS Alpha equivalent to this is:

. The last command compiles the main program and links the object

mainprog.cob

, which contains the main program

calc

array_calc.o

. The second command creates the ﬁle

calc

, you can run the

$ COBOL proga1+proga2+proga3,progb1+progb2

1.2.2.6 Debugging a Program

To debug a program using the Ladebug Debugger, compile the source ﬁles with the-gﬂag to request additional symbol table information for source line debugging in the object and executable program ﬁles. The following command also uses the-oﬂag to name the executable program ﬁle

% cobol -g -o calc_debug mainprog.cob array_calc.cob calc_aver.cob

To debug an executable program named calc_debug, type the following command:

% ladebug calc_debug

For more information on running the program within the debugger, see the Ladebug Debugger Manual.

1.2.2.7 Output Files: Object, Executable, Listing, and Temporary Files

The output produced by the

• An object ﬁle, if you specify the-cﬂag on the command line

• An executable ﬁle, if you omit the-cﬂag

• A listing ﬁle, if you specify the-Vﬂag

If the environment variable TMPDIR is set, the value is used as the directory for temporary ﬁles.

You control the production of these ﬁles by specifying the appropriate ﬂags on the

cobol

single temporary object ﬁle, whether you specify one source ﬁle or multiple source ﬁles separated by blanks. Theldlinker is then invoked to link the object ﬁle into one executable image ﬁle.

command line. Unless you specify the-cﬂag, the compiler generates a

cobol

command includes:

cobol

calc_debug

1–16 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

The object ﬁle is in Tru64 UNIX extended the following information:

• The name of the entry point. It takes this name from the program name in the ﬁrst PROGRAM-ID paragraph in the source program.

• A list of variables that are declared in the module. The linker uses this information when it binds two or more modules together and must resolve references to the same names in the modules.

• A symbol table and a source line correlation table (if you request them with the external and internal variables within a module, with deﬁnitions of their locations. The source line correlation table associates lines in your source ﬁle with lines in your program. These tables are of use in debugging.

If severe errors are encountered during compilation or if you specify certain ﬂags

-c

such as

1.2.2.8 Naming Output Files

To specify a ﬁle name (other than

-o

output ﬂag, where output speciﬁes the ﬁle name. You can also use the

command to rename the ﬁle. The following command requests a ﬁle name of

prog1.out

% cobol -o prog1.out test1.cob

Besides specifying the name of the executable image ﬁle, you can use the output ﬂag to rename the object ﬁle if you speciﬁed the-cﬂag. If you specify the

-c

ﬂag and omit the-ooutput ﬂag, the name of the ﬁrst speciﬁed ﬁle is used with

a.osufﬁx substituted for the source ﬁle sufﬁx.

, linking does not occur.

for the source ﬁle

coff

format. The object ﬁle provides

-g

ﬂag, for debugging). A symbol table is a list of the names of all

a.out

) for the executable image ﬁle, use the

test1.cob

-o

1.2.2.9 Temporary Files

Temporary ﬁles created by the compiler or a preprocessor reside in the directory and are deleted (unless the-Kﬂag is speciﬁed). You can set the environment variable TMPDIR to specify a directory to contain temporary ﬁles if

/tmp

is not acceptable.

To view the ﬁle name and directory where each temporary ﬁle is created, use the-vﬂag. To create object ﬁles in your current working directory, use the ﬂag. Any object ﬁles (.oﬁles) that you specify on the retained.

1.2.2.10 Examples of the COBOL Command

The following examples show the use of the followed by a description of the output ﬁles that it produces.

% cobol -V aaa.cob bbb.cob ccc.cob

The Compaq COBOL source ﬁles into temporary object ﬁles. The temporary object ﬁles are passed to the linker. Theldlinker produces the executable ﬁle the compiler to create the listing ﬁles

cobol

aaa.cob,bbb.cob

command. Each command is

, and

a.out

aaa.lis,bbb.lis

/tmp

-c

command line are

ccc.cob

are compiled

. The-Vﬂag causes

, and

ccc.lis

Developing Compaq COBOL Programs 1–17

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

% cobol -V *.cob

Compaq COBOL source ﬁles with ﬁle names that end with .cob are compiled into temporary object ﬁles, which are then passed to theldlinker. The linker produces the a.out ﬁle.

When the compilation completes, the status values:

0—SUCCESS 1—FAILURE 2—SUBPROCESS_FAILURE ( 3—SIGNAL

1.2.2.11 Other Compilers

You can compile and link multilanguage programs using a single The

cobol

command recognizes C or Assembler program ﬁles by their ﬁle sufﬁx characters and passes them to thecccompiler for compilation. Before compilation,

applies the

cpp

preprocessor to ﬁles that it recognizes, such as

any ﬁle with a.csufﬁx. Certain ﬂags passed toccare passed to theldlinker.

1.2.2.12 Interpreting Messages from the Compiler

The Compaq COBOL compiler identiﬁes syntax errors and violations of language rules in the program. If the compiler ﬁnds any errors, it writes messages to the

stderr

output ﬁle and any listing ﬁle. If you enter the

interactively, the messages are displayed on your terminal. Compiler messages have the following format:

cobol: severity: filename, line n, message-text [text-in-error]

--------^

cobol

driver returns one of the following

cobolorcc

)

cobol

command.

command

The pointer (

--^

) indicates the exact place on the source line where the error was found. For example, the following error message shows the format and message text in a listing ﬁle when an END DO statement was omitted:

cobol: Severe: disp.cob, line 7: Missing period is assumed

05 VAR-1 PIC X.

--------^

The severity level is one of the following:

Severe The compiler does not produce an object module. You must correct

Error The compiler makes an assumption about what you intended and

Warning The compiler attempts to correct the error in the statement,

Informational This message usually appears with other messages to inform you

the error before you can compile the program to produce an object module.

continues. However, the compiler’s assumption may not relate to your intention. Correct the error.

but you should verify that the compiler’s action is acceptable. Otherwise, your program may produce unexpected results.

of speciﬁc actions taken by the compiler. No action is necessary on your part.

1–18 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Any messages issued during the compilation are inserted in the listing ﬁle. A listing ﬁle is useful for debugging the source code. Use the-Vor produce a listing; you may also use

-machine_code,-map

ﬁle. Diagnostic messages provide information for you to determine the cause of an

error and correct it. If the compiler creates a listing ﬁle, it writes the messages to the listing ﬁle.

, and/or

-warn

-cross_reference,-copy_list,-flagger

, all of which affect the contents of the listing

1.2.3 Linking a Compaq COBOL Program on Tru64 UNIX

Once your program has compiled successfully, the system passes the resulting object ﬁle (which has the sufﬁx .o by default) to the linker to create an executable image ﬁle. By default, the executable image ﬁle has the name a.out. (To change

-o

this default, specify on the Tru64 UNIX system.

Theldlinker provides the following primary functions:

• Generates appropriate information in the executable image for virtual memory allocation

• Resolves symbolic references among object ﬁles being linked, including whether to search in archive or shared object libraries

ﬁlename on the

cobol

command line.) This ﬁle can be run

-list

ﬂag to

• Assigns values to relocatable global symbols

• Performs relocation

The linker produces an executable program image with a default name of a.out. When you enter a

a compilation error occurs or you specify the

1.2.3.1 Specifying Object Libraries for Linking

You can specify object libraries on the ﬂags or by providing the ﬁle name of the library. These object libraries are also searched byldfor unresolved external references.

When library ﬁle names told. Theldlinker tries to locate each of these library ﬁle names in a standard list of library directories. That is,ldattempts to locate each object library ﬁle name ﬁrst in one directory, then in the second, and then in the third directory on its search list of directories.

To display a list of the compilers invoked, ﬁles processed, and libraries accessed during linking, specify the

In addition to an object ﬁle created by the compiler, any linker ﬂags and object ﬁles speciﬁed on the linker loads object ﬁles according to the order in which they are speciﬁed on the command line. Because of this, you must specify object libraries after all source and object ﬁles on the

cobol

speciﬁes certain libraries told, it provides a standard list of COBOL

command, theldlinker is invoked automatically unless

-v

ﬂag.

cobol

command are also passed to theldlinker. The

cobol

command line.

COBOL

-c

ﬂag on the command line.

command line by using certain

To help identify undeﬁned references to routines or other symbols in an object

module, consider using the the

command ﬁltered by the

% cobol -c ex.cob % nm -o ex.o | grep U

command. For instance, in the following example

grep

command lists all undeﬁned (U) symbols:

Developing Compaq COBOL Programs 1–19

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

If the symbol is undeﬁned, U appears in the column before the symbol name. Any symbols withaUintheir names can also be displayed by this use of

1.2.3.2 Specifying Additional Object Libraries

You can control the libraries as follows:

• To specify additional object library ﬁle names forldto locate, use the

-l

string ﬂag to deﬁne an additional object library forldto search. Thus, each occurrence of the-lstring ﬂag speciﬁes an additional ﬁle name that is added to the list of object libraries for names searched (shown in the form of the appropriate

-lcob

-lcurses

-lFutil

-lots2

-lots

-lisam

-lsort

-lexc

-lm

For instance, the ﬁle name of The following example speciﬁes the additional library

grep

to locate. The standard COBOL library ﬁle

-l

string ﬂag) are:

-lcobislibcob

libX

% cobol simtest.cob -lX

• In addition to the standard directories in whichldtries to locate the library ﬁle names, you can use the-Ldir ﬂag to specify another directory. The

-l

string ﬂag and-Ldir ﬂag respectively adds an object library ﬁle name

(-lstring) or directory path (-Ldir) thatlduses to locate all speciﬁed library

ﬁles. The standard the

-L

dir ﬂag.

The following example speciﬁes the additional object library path

/usr/lib/mytest

% cobol simtest.cob -L/usr/lib/mytest

• You can indicate thatldshould not search its list of standard directories at all by specifying the-Lﬂag. When you do so, you must specify all libraries on the standard libraries. To specify all libraries, you might use the-Lﬂag in combination with the-Ldir ﬂag on the same

• You can specify the pathname and ﬁle name of an object library as you would specify any ﬁle. Specifying each object library that resides in special directories in this manner is an alternative to specifying the library using the

-l

linker must do to locate all the needed object ﬁles. In certain cases, you may need to specify the pathname and ﬁle name instead

of using the-lstring or-Ldir ﬂags for the linker to resolve global symbols with shared libraries.

cobol

string or-Ldir ﬂag. This method can reduce the amount of searching the

command line in some form, including the directory for

directories are searched before directories speciﬁed by

cobol

command line.

cobol

When processing a C source ﬁle ( need to specify the appropriate C libraries using the

1–20 Developing Compaq COBOL Programs

sufﬁx) using the

cobol

-l

string ﬂag.

command, you may

1.2.3.3 Specifying Types of Object Libraries

Certain object ( libraries speciﬁed using the-lstring or-Ldir ﬂags. These ﬂags are the following:

cobol

.so

ﬂags inﬂuence whetherldsearches for an archive (.a) or shared

) library on the standard list of COBOL libraries and any additional

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

• The

External references found in an archive library result in that routine being included in the resulting executable program ﬁle at link time.

External references found in a shared object library result in a special link to that library being included in the resulting executable program ﬁle, instead of the actual routine itself. When you run the program, this link gets resolved by either using the shared library in memory (if it already exists) or loading it into memory from disk.

1.2.3.4 Creating Shared Object Libraries

To create a shared library, ﬁrst create the following example:

-call_shared

before.aﬁles. Asldattempts to resolve external symbols, it looks at the shared library ﬁrst before the corresponding archive library. References to symbols found in a run time. References to symbols found in.alibraries are loaded into the executable image ﬁle at link time. For instance, searched before

-non_shared

module created contains static references to external routines and are loaded into the executable image at link time, not at run time. Corresponding ﬁles are not searched.

The following example requests that the standard instead of the corresponding

% cobol -non_shared mainprog.cob rest.o

ﬂag, the default, indicates that

/usr/lib/libc.a

ﬂag indicates that only.aﬁles are searched, so the object

.so

ﬁles are searched

.so

library are dynamically loaded into memory at

/usr/shlib/libc.so

.so

ﬁles:

ﬁle, such as

cobol .a

ﬁles be searched

octagon.o

.so

in the

% cobol -O3 -c octagon.cob

The ﬁle library, named

% ld -shared -no_archive octagon.o \

A description of eachldﬂag follows:

• The

• The name of the object module is

• The

octagon.o

-lcob -lcurses -lFutil -lots2 -lots -lisam -lsort -lexc -lmld -lm

-shared

-no_archive

resolve external names (only shared libraries).

-lcob

COBOL command would have otherwise passed told. When you create a shared library, all symbols must be resolved. For more information about the standard list of libraries used by Compaq COBOL, see Section 1.2.3.2.

is then used as input to theldcommand to create the shared

octagon.so

ﬂag is required to create a shared library.

and subsequent ﬂags are the standard list of libraries that the

ﬂag indicates thatldshould not search archive libraries to

octagon.o

. You can specify multiple.oﬁles.

Developing Compaq COBOL Programs 1–21

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

1.2.3.5 Shared Library Restrictions

When creating a shared library usingld, be aware of the following restrictions:

• Programs that are installed have been installed using the shared libraries (for security reasons).

• For other restrictions imposed by the operating system, see your operating system documentation. If you create a shared library that contains routines written in C, refer to your operating system documentation for any restrictions associated with thecccommand.

1.2.3.6 Installing Shared Libraries

Once the shared library is created, it must be installed before you run a program that refers to it. The following describes how you can install a shared library for private or systemwide use:

• To install a private shared library, such as for testing, set the environment variable LD_LIBRARY_PATH, as described in ld(1).

• To install a systemwide shared library, place the shared library ﬁle in one of the standard directory paths used byld(see ld(1).

For complete information on installing shared libraries, see your operating system documentation.

Specifying Shared Object Libraries

When you link your program with a shared library, all symbols must be referenced before libraries at the end of the you specify the corresponding archive libraries.

-non_shared

setuidorsetgid

inlib

searches the shared library, so you should always specify

cobol

command line after all ﬁle names. Unless

ﬂag, shared libraries will be searched before the

shell command, but only systemwide

will not use any libraries that

For instance, the following command generates an error if the ﬁle references routines in the library

% cobol -call_shared test.cob -lX rest.o

The correct order follows:

% cobol -call_shared test.cob rest.o -lX

Link errors can occur with symbols that are deﬁned twice, as when both an archive and shared object are speciﬁed on the same command line. In general, specify any archive libraries after the last ﬁle name, followed by any shared libraries at the end of the command line.

Before you reference a shared library at run time, it must be installed.

1.2.3.7 Interpreting Messages from the Linker

If the linker detects any errors while linking object modules, it displays messages about their cause and severity. If any errors occur, the linker does not produce an image ﬁle.

Linker messages are descriptive, and you do not normally need additional information to determine the speciﬁc error. The general format for follows:

ld:

message-text

libX

rest.o

messages

1–22 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

The message-text may be on multiple lines and is sometimes accompanied by a

cobol

Some common errors that occur during linking resemble the following:

• An object module has compilation errors. This error occurs when you attempt

• The modules being linked deﬁne more than one transfer address. The linker

• A reference to a symbol name remains unresolved. This error occurs when

If an error occurs when you link modules, you may be able to correct it by retyping the command string and specifying the correct routines or libraries ( command line.

error.

to link a module that had warnings or errors during compilation. Although you can usually link compiled modules for which the compiler generated messages, you should verify that the modules will actually produce the output you expect.

generates a warning if more than one main program has been deﬁned. This can occur, for example, when an extra END statement exists in the program. The image ﬁle created by the linker in this case can be run; the entry point to which control is transferred is the ﬁrst one that the linker found.

you omit required module or library names from the and the linker cannot locate the deﬁnition for a speciﬁed global symbol reference.

-l

string ﬂag,-Ldir ﬂag), or specify the object library or object modules on the

cobolorld

command

1.2.4 Running a Compaq COBOL Program on Tru64 UNIX

The simplest form of the run command to execute a program is to type its ﬁle name at the operating system prompt, as follows:

% myprog.out

In addition to normal IO accesses, your Compaq COBOL programs can read command-line arguments and access (read and write) environment variables.

1.2.4.1 Accessing Command-Line Arguments

Command-line arguments allow you to provide information to a program at run time. Your program provides the logic to parse the command line, identify command-line options, and act upon them. For example, you might develop a program that will extract a given amount of data from a speciﬁed ﬁle, where both the number of records to read and the ﬁle name are highly dynamic, changing for each activation of your program. In this case your program would contain code that reads a command-line argument for the number of records to read, and a second argument for the ﬁle speciﬁcation. Your program execution command could look like the following:

% myprog 1028 powers.dat

In the preceding example the program ﬁle powers.dat.

Multiple command-line arguments are delimited by spaces, as shown in the preceding example. If an argument itself contains spaces, enclose that argument in quotation marks (" ") as follows:

myprog

would read 1028 records from the

% myprog2 "all of this is argument 1" argument2

Developing Compaq COBOL Programs 1–23

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

You provide deﬁnitions for the command-line arguments with the SPECIALNAMES paragraph in your program’s Environment Division, and you include ACCEPT and DISPLAY statements in the Procedure Division to parse the command line and access the arguments. Detailed information about commandline argument capability is in the ACCEPT and DISPLAY sections in the Compaq COBOL Reference Manual.

1.2.4.2 Accessing Environment Variables

You can read and write environment variables at run time through your Compaq COBOL program.

Example 1–1 allows you to specify a ﬁle speciﬁcation by putting the directory in the value of the environment variable COBOLPATH, and the ﬁle name in a command-line argument:

Example 1–1 Accessing Environment Variables and Command-Line Arguments

identification division. PROGRAM-ID. MYPROG. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES.

SYSERR IS STANDARD-ERROR ENVIRONMENT-NAME IS NAME-OF-ENVIRONMENT-VARIABLE ENVIRONMENT-VALUE IS ENVIRONMENT-VARIABLE ARGUMENT-NUMBER IS POS-OF-COMMAND-LINE-ARGUMENT ARGUMENT-VALUE IS COMMAND-LINE-ARGUMENT.

WORKING-STORAGE SECTION. 01 howmany-records PIC 9(5). 01 env-dir PIC x(50). 01 file-name PIC x(50). 01 file-spec PIC x(100). PROCEDURE DIVISION. BEGIN.

ACCEPT howmany-records FROM COMMAND-LINE-ARGUMENT

ON EXCEPTION

DISPLAY "No arguments specified"

UPON STANDARD-ERROR END-DISPLAY STOP RUN

END-ACCEPT.

1–24 Developing Compaq COBOL Programs

(continued on next page)

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Example 1–1 (Cont.) Accessing Environment Variables and Command-Line

Arguments

DISPLAY "COBOLPATH" UPON NAME-OF-ENVIRONMENT-VARIABLE. ACCEPT env-dir FROM ENVIRONMENT-VARIABLE

ON EXCEPTION

DISPLAY "Environment variable COBOLPATH is not set"

UPON STANDARD-ERROR

END-DISPLAY

NOT ON EXCEPTION

ACCEPT file-name FROM COMMAND-LINE-ARGUMENT

ON EXCEPTION

DISPLAY "Attempt to read beyond end of command line"

UPON STANDARD-ERROR

END-DISPLAY

NOT ON EXCEPTION

STRING env-dir "/" file-name delimited by " " into file-spec DISPLAY "Would have read " howmany-records " records from " file-spec

END-ACCEPT

END-ACCEPT.

This example requires that the following command has been executed to set an environment variable:

% setenv COBOLPATH /usr/files

When you execute the following command lines:

% cobol -o myprog myprog.cob % myprog 1028 powers.dat

The following will result:

• howmany-records will contain ‘‘1028’’

• env-dir will contain ‘‘/usr/ﬁles’’

• ﬁle-name will contain ‘‘powers.dat’’

• ﬁle-spec will contain ‘‘/usr/ﬁles/powers.dat’’ For additional information, see the ACCEPT and DISPLAY statements in the

Compaq COBOL Reference Manual.

1.2.4.3 Errors and Switches

See Section 1.4 for a discussion of errors that can cause incorrect or undesirable results when you run a program.

See Section 1.5 for a discussion of controlling program execution with switches.

1.2.5 Program Development Stages and Tools

This manual primarily addresses the program development activities associated with development and testing phases. For information about topics usually considered during application design, speciﬁcation, and maintenance, see your operating system documentation, appropriate reference pages, or appropriate commercially published documentation.

Developing Compaq COBOL Programs 1–25

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

Table 1–3 lists and describes some of the software tools you can use when developing and testing a program.

Table 1–3 Main Tools for Program Development and Testing

Task or Activity Tool and Description

Manage source ﬁles Use

Create and modify source ﬁles

Analyze source code Use searching commands such as

Build program (compile and link)

Debug and test program Use the Ladebug Debugger to debug your program or run it for

Install program Use

RCSorsccs

see the Tru64 UNIX documentation on programming support tools or the appropriate reference page.

Use a text editor, such as more information, see your operating system documentation.

more information, see the Tru64 UNIX documentation on programming support tools or the appropriate reference page.

You can use the perhaps using shell scripts, or use the your application in an automated fashion using a makeﬁle. For more information on and the Tru64 UNIX documentation on programming support tools.

general testing. For more information on Ladebug Debugger, see the Ladebug Debugger Manual.

setld

more information, see the Tru64 UNIX documentation on programming support tools.

to manage source ﬁles. For more information,

vi,emacs

cobol

command to create small programs,

make

and related commands such as

, or another editor. For

grep

and

diff

make

command to build

, see the make(1) reference page

tar

. For

In addition, you might use the following shell commands at various times during program development:

• To view information about an object ﬁle or an object library, use the following commands:

The

file

command shows the type of a ﬁle (such as which programming

language, whether it is an object library, ASCII ﬁle, and so forth). Thenmcommand (perhaps with the-aor-oﬂag) shows symbol table

information, including the identiﬁcation ﬁeld of each object ﬁle. The The

odump size

command shows the contents of a ﬁle and other information.

command shows the size of the code and data sections.

For more information on these commands, see the appropriate reference page or the DIGITAL UNIX Programmer’s Guide.

• Use thearcommand to create an archive object library (-rﬂag), maintain the modules in the library, list the modules in the library (-t), and perform

-ts

other functions. Use

to add a table of contents to the object library for linking purposes. For more information, see ar(1) or the DIGITAL UNIX Programmer’s Guide.

• To create shared libraries on Tru64 UNIX systems, useld, not the

command. For more information, refer to Section 1.2.3.4 and the DIGITAL UNIX Programmer’s Guide.

1–26 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.2 Developing Programs on Tru64 UNIX

• The

In most instances, use the compiler and theldlinker. To link one or more object ﬁles created by the Compaq COBOL compiler, you should use the because the COBOL Run-Time Libraries when it invokes your current working directory, specify the directory path in addition to the ﬁle name. ♦

Compilation does the following for you:

• Detects errors in your program syntax

• Displays compiler messages on your terminal screen

• Generates machine language instructions from valid source statements

• Groups the instructions into an object module for the linker

strip

minimize image size. For additional information, see strip(1).

The CALL dataname, CANCEL, and the Compaq extensions to the ACCEPT and DISPLAY statements will not work correctly if you use the

strip

command removes symbolic and other debugging information to

Note

command on your image.

cobol

command automatically references the appropriate Compaq

command to invoke both the Compaq COBOL

cobol

command instead of theldcommand,

. If the executable image is not in

• Launches the linker with the compiled ﬁle or ﬁles

• Creates an executable image You use the COBOL command to compile and link your program. The COBOL

command invokes the Compaq COBOL compiler driver that is the actual user interface to the Compaq COBOL compiler. The compiler driver can accept command options and multiple ﬁle names, and normally causes the compiler and linker to process each ﬁle. A variety of qualiﬁers to the compile command are available to specify optional processing and to specify the names of output ﬁles.

After the Compaq COBOL compiler processes the source ﬁles to create one or more object ﬁles, the compiler driver passes a list of object ﬁles and other information to the linker.

1.3 Developing Programs on OpenVMS Alpha

You use DCL commands (commands used at the OpenVMS Alpha system prompt) to create, compile, link, and run Compaq COBOL programs on OpenVMS Alpha systems.

1.3.1 Creating a Compaq COBOL Program on OpenVMS Alpha

To create and modify a Compaq COBOL program, you must invoke a text editor. The default editor for OpenVMS Alpha is the DEC Text Processing Utility (DECTPU). Other editors, such as EDT or the Language-Sensitive Editor (LSE), may be available on your system. Check with your system administrator and refer to the OpenVMS EDT Reference Manual (this manual has been archived but is available on the OpenVMS Documentation CD-ROM) for more information about EDT or the Guide to Language-Sensitive Editor for additional information about LSE.

Developing Compaq COBOL Programs 1–27

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Figure 1–2 DCL Commands for Developing Programs

COMMANDS

EDIT/TPU PROG_1.COB

Use the file type of to indicate the file contains a Compaq COBOL program.

COBOL PROG_1$ The Command

COBOL

assumes the file type of an input file is .

(if you use the qualifier, the compiler creates a listing file.)

LINK PROG_1

The command assumes

LINK

the file type of an input file is .

OBJ

(If you use the qualifier, the linker creates a map file.)

RUN PROG_1

RUN

The command assumes the file type of an image is

EXE

COB

/LIST

/MAP

ACTION

Create a

source program

Compile the

source program

Link the

object module

Run the

executable

image

INPUT/OUTPUT FILES

PROG_1.COB

PROG_1.OBJ

(PROG_1.LIS)

libraries

PROG_1.EXE

(PROG_1.MAP)

VM-0611A-AI

Figure 1–2 shows the basic steps in Compaq COBOL program development. Use the text editor of your preference to create and revise your source ﬁles. For

example, the following command line invokes the DECTPU editor and creates the source ﬁle PROG_1.COB:

$ EDIT PROG_1.COB

The ﬁle type .COB is used to indicate that you are creating a Compaq COBOL program. COB is the default ﬁle type for all Compaq COBOL programs.

The COPY Statement, Dictionaries and Libraries

Including the COPY statement in your program allows separate programs to share common source text, reducing development and testing time as well as storage requirements. You can use the COPY statement to access modules in libraries. The COPY statement causes the compiler to read the ﬁle or module speciﬁed during the compilation of a program. When the compiler reaches the end of the included text, it resumes reading from the previous input ﬁle.

By using the /INCLUDE qualiﬁer on the COBOL command line, you can set up a search list for ﬁles speciﬁed by the COPY statement. For more information, see the Compaq COBOL Reference Manual.

1–28 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

You can use the COPY FROM DICTIONARY statement in your program to access a data dictionary and copy Oracle CDD/Repository record descriptions into your program as COBOL record descriptions. Before you can copy record descriptions from Oracle CDD/Repository, you must create the record descriptions using the Common Data Dictionary Language (CDDL) or Common Dictionary Operator (CDO).

For more information about using Oracle CDD/Repository and creating and maintaining text libraries, refer to the Compaq COBOL Reference Manual and Using Oracle CDD/Repository on OpenVMS Systems.

1.3.2 Compiling a Compaq COBOL Program on OpenVMS Alpha

To compile your program, use the COBOL command. The Compaq COBOL compiler performs these primary functions:

• Detects errors in your program

• Displays each compiler message on your terminal screen

• Generates machine language instructions from valid source statements

• Groups these language instructions into an object module for the linker

• Creates an analysis ﬁle if you request it with the /ANALYSIS_DATA qualiﬁer. SCA uses this ﬁle to display information about program symbols and source ﬁles.

The compiler outputs an object module that provides the following information:

• The name of the entry point. It takes this name from the program name in the ﬁrst PROGRAM-ID paragraph in the program.

• A list of variables that are declared in the module. The linker uses this information when it binds two or more modules together and must resolve references to the same names in the modules.

• Traceback information. This information is used by the system default condition handler when an error occurs that is not handled by the program. The traceback information permits the default handler to display a list of the active blocks in the order of activation; this is an aid in program debugging.

• A symbol table and a source line correlation table, only if you request them with the /DEBUG qualiﬁer. A symbol table is a list of the names of all external and internal variables within a module, with deﬁnitions of their locations. The source line correlation table associates lines in your source ﬁle with lines in your program. These tables are of primary help when you use the OpenVMS Debugger.

To invoke the Compaq COBOL compiler, use the COBOL command (explained in Section 1.3.2.1). You can specify qualiﬁers with the COBOL command. The following sections discuss the COBOL command and its qualiﬁers.

1.3.2.1 Format of the COBOL Command on OpenVMS Alpha

The COBOL command has the following format:

COBOL [/qualiﬁer] ... {ﬁle-spec [/qualiﬁer] ...} ...

Developing Compaq COBOL Programs 1–29

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

/qualiﬁer

Speciﬁes an action to be performed by the compiler on all ﬁles or speciﬁc ﬁles listed. When a qualiﬁer appears directly after the COBOL command, it affects all the ﬁles listed. By contrast, when a qualiﬁer appears after a ﬁle speciﬁcation, it affects only the ﬁle that immediately precedes it. However, when ﬁles are concatenated, these rules do not apply.

ﬁle-spec

Speciﬁes an input source ﬁle that contains the program or module to be compiled. You are not required to specify a ﬁle type; the Compaq COBOL compiler assumes the default ﬁle type COB. If you do not provide a ﬁle speciﬁcation with the COBOL command, the system prompts you for one.

1.3.2.2 Compiling Multiple Files

You can include more than one ﬁle speciﬁcation on the same command line by separating the ﬁle speciﬁcations with either a comma (,) or a plus sign (+). If you separate the ﬁle speciﬁcations with commas, you can control which source ﬁles are affected by each qualiﬁer. In the following example, the Compaq COBOL compiler creates an object ﬁle for each source ﬁle but creates only a listing ﬁle for the source ﬁles entitled PROG_1 and PROG_3:

$ COBOL/LIST PROG_1, PROG_2/NOLIST, PROG_3

If you separate ﬁle speciﬁcations with plus signs, the Compaq COBOL compiler concatenates each of the speciﬁed source ﬁles and creates one object ﬁle and one listing ﬁle. In the following example, only one object ﬁle, PROG_1.OBJ, and one listing ﬁle, PROG_1.LIS, are created. Both of these ﬁles are named after the ﬁrst source ﬁle in the list, but contain all three modules.

$ COBOL PROG_1 + PROG_2/LIST + PROG_3

Any qualiﬁers speciﬁed for a single ﬁle within a list of ﬁles separated with plus signs affect all ﬁles in the list.

1.3.2.3 Debugging a Program

To effectively debug a Compaq COBOL program, you must ﬁrst make symbol and traceback information available by adding the DEBUG option to the compile command line. You specify the /DEBUG option as follows:

$ COBOL/DEBUG myprog $ LINK/DEBUG myprog $ RUN/DEBUG myprog

This enables you to examine and modify variables, monitor ﬂow of control, and perform various other debugging techniques. See HELP COBOL/DEBUG, HELP DEBUG, and Section C.4, OpenVMS Debugger (OpenVMS) for additional information.

When you compile a program with /DEBUG, you should also specify /NOOPTIMIZE (-O0) to expedite your debugging session. (The default is /OPTIMIZE (-O).) Optimization often changes the order of execution of the object code generated for statements in a program, and it might keep values in registers and deallocate user variables. These effects can be confusing when you use the debugger. (A diagnostic message warns you if you compile a Compaq COBOL program with /DEBUG without specifying anything about optimization on the command line.)

1–30 Developing Compaq COBOL Programs

1.3.2.4 Separately Compiled Programs

If a compilation unit consists of multiple separately compiled programs (SCPs), by default the Compaq COBOL compiler produces a single object ﬁle that consists of a single module with multiple embedded procedures. This object ﬁle can be inserted into an object library. If your build procedure requires that the linker extract any part of the module, the linker must extract the entire object.

If you use /SEPARATE_COMPILATION on the compile command line Compaq COBOL will compile multiple SCPs into a single object ﬁle that consists of a concatenation of modules, each containing a single procedure. This object may then be inserted into an object library from which the linker can extract just the procedures that are speciﬁcally needed.

1.3.2.5 COBOL Qualiﬁers

COBOL options (also known as qualiﬁers or ﬂags) control the way in which the compiler processes a ﬁle. You can process your ﬁle with the COBOL command alone or you can select options that offer you alternatives for developing, debugging, and documenting programs.

If you compile parts of your program (compilation units) using multiple COBOL commands, options that affect the execution of the program should be used consistently for all compilations, especially if data will be shared or passed between procedures.

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Table 1–4 lists the COBOL command options and their defaults. For more information about COBOL options, invoke online help for COBOL at the system prompt.

Note

Brackets ([]) indicate that the enclosed item is optional. If you specify more than one option for a single qualiﬁer, you must separate each option with a comma and enclose the list of options in parentheses.

Developing Compaq COBOL Programs 1–31

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Table 1–4 COBOL Command Qualiﬁers

Qualiﬁer Default

/ALIGNMENT[=[NO]PADDING] or /NOALIGNMENT

/ANALYSIS_DATA[=ﬁle-spec] or /NOANALYSIS_DATA

/ANSI_FORMAT or /NOANSI_FORMAT /NOANSI_FORMAT

/ARCHITECTURE=

/ARITHMETIC=

[NO]PERFORM [NO]BOUNDS

6 6

/CHECK=

or /NOCHECK

[NO]DECIMAL

[NO]DUPLICATES

ALL NONE

GENERIC

HOST

EV4

EV5 EV56

EV6

EV67 PCA56

STANDARD NATIVE

9 >

= >

;

3 7

,...

7 5

/NOALIGNMENT

/NOANALYSIS_DATA

/ARCHITECTURE=GENERIC

/ARITHMETIC=NATIVE

/NOCHECK or /CHECK=NONE

/CONDITIONALS=(character,...) or /NOCONDITIONALS

/CONVERT=[NO]LEADING_BLANKS or /NOCONVERT

/COPY_LIST or /NOCOPY_LIST /NOCOPY_LIST

/CROSS_REFERENCE=

ALPHABETICAL DECLARED

or /NOCROSS_REFERENCE

This is the default keyword when using the named option with no keywords.

,...

/NOCONDITIONALS

/NOCONVERT

/NOCROSS_REFERENCE

(continued on next page)

1–32 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Table 1–4 (Cont.) COBOL Command Qualiﬁers

Qualiﬁer Default

/DEBUG=

or /NODEBUG

[NO]SYMBOLS [NO]TRACEBACK ALL NONE

3 5

,...

/DEBUG=TRACEBACK /DEBUG=ALL /DEBUG=(TRACEBACK,SYMBOLS)

/DEPENDENCY_DATA or /NODEPENDENCY_DATA

/DIAGNOSTICS[=ﬁle-spec] or /NODIAGNOSTICS

/DISPLAY_FORMATTED or /NODISPLAY_FORMATTED

/FIPS=74 or /NOFIPS /NOFIPS

2 6

6 6

/FLAGGER=

or /NOFLAGGER

/FLOAT=

6 6 6 6 4

D_FLOAT G_FLOAT IEEE_FLOAT

HIGH_FIPS INTERMEDIATE_FIPS MINIMUM_FIPS OBSOLETE OPTIONAL_FIPS REPORT_WRITER SEGMENTATION SEGMENTATION_1

3 7

7 7 7

,...

7 7 7 5

/NODEPENDENCY_DATA

/NODIAGNOSTICS

/NODISPLAY_FORMATTED

/NOFLAGGER

/FLOAT=D_FLOAT

/GRANULARITY=

/HELP or /NOHELP /NOHELP

/INCLUDE=ﬁle-spec or /NOINCLUDE /NOINCLUDE /KEEP or /NOKEEP /NOKEEP

/LIST[=ﬁlename.ext] or /NOLIST /NOLIST

This is the default keyword when using the named option with no keywords.

BYTE LONGWORD QUADWORD

/GRANULARITY=QUADWORD

/LIST (batch)

Developing Compaq COBOL Programs 1–33

(continued on next page)

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Table 1–4 (Cont.) COBOL Command Qualiﬁers

Qualiﬁer Default

/MACHINE_CODE or /NOMACHINE_CODE

/MAP= or /NOMAP

/MATH_INTERMEDIATE=

/NAMES=

/NATIONALITY=

/OBJECT[=ﬁlename.ext] or /NOOBJECT Temporary names used

ALPHABETICAL DECLARED

AS_IS

LOWER LOWERCASE

UPPER

UPPERCASE

JAPAN

(

,...

CIT3 CIT4 FLOAT

9 >

= >

;

)

/NOMACHINE_CODE

/NOMAP

/MATH_INTERMEDIATE=FLOAT

/NAMES=LOWERCASE

/NATIONALITY=US

/OPTIMIZE[=



LEVEL=



  



TUNE=



or /NOOPTIMIZE

This is the default keyword when using the named option with no keywords.

/OPTIMIZE=0 is functionally equivalent to /NOOPTIMIZE.

1 2

GENERIC

HOST

EV4

EV5 EV56

EV6

EV67

PCA56

9 >

= >

;



= >

;

]



;

/OPTIMIZE= (LEVEL=4,TUNE=GENERIC)

(continued on next page)

1–34 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Table 1–4 (Cont.) COBOL Command Qualiﬁers

Qualiﬁer Default

/RESERVED_WORDS=

[NO]200X [NO]XOPEN [NO]FOREIGN_EXTENSIONS

,...

/RESERVED_WORDS=(XOPEN, NO200X, NOFOREIGN_EXTENSIONS)

/SEPARATE_COMPILATION or /NOSEPARATE_COMPILATION

/SEQUENCE_CHECK or /NOSEQUENCE_CHECK

/SOURCE[=ﬁlename.ext] Source is ﬁlename.COB

85 [NO]MIA

/STANDARD=

or /NOSTANDARD

/TIE or /NOTIE /NOTIE

/TRUNCATE or /NOTRUNCATE /NOTRUNCATE

/VFC or /NOVFC /VFC

/WARNINGS=

or /NOWARNINGS

[NO]SYNTAX

[NO]V3 [NO]XOPEN

[NO]INFORMATION [NO]OTHER

ALL NONE

3 7

,...

3 5

,...

/NOSEPARATE_COMPILATION

/NOSEQUENCE_CHECK

/STANDARD=85

/WARNINGS=OTHER

This is the default keyword when using the named option with no keywords.

1.3.2.6 Common Command-Line Errors to Avoid

The following are some common errors to avoid when entering COBOL command lines:

• Omitting /ANSI_FORMAT for programs that are in ANSI format (AREA A, AREA B, and so forth)

• Including contradictory options

• Omitting a necessary qualiﬁer, such as /LIST if you specify /MAP

• Omitting version numbers from ﬁle speciﬁcations when you want to compile a program that is not the latest version of a source ﬁle

Developing Compaq COBOL Programs 1–35

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

• Forgetting to use a ﬁle sufﬁx in the ﬁle speciﬁcation, or not specifying /SOURCE when your source ﬁle sufﬁx is not .COB or .CBL

1.3.2.7 Compiling Programs with Conditional Compilation

To debug source code that contains conditional compilation lines, you can use either the /CONDITIONALS qualiﬁer or the WITH DEBUGGING MODE clause. The /CONDITIONALS qualiﬁer is listed in Table 1–4. For more information about the /CONDITIONALS qualiﬁer, invoke the online Help facility for Compaq COBOL at the system prompt. For more information about the WITH DEBUGGING MODE clause, refer to the Compaq COBOL Reference Manual.

Using the WITH DEBUGGING MODE clause as part of the SOURCECOMPUTER paragraph causes the compiler to process all conditional compilation lines in your program as COBOL text. If you do not specify the WITH DEBUGGING MODE clause, and if the /CONDITIONALS qualiﬁer is not in effect, all conditional compilation lines in your program are treated as comments.

The WITH DEBUGGING MODE clause applies to: ( 1 ) the program that speciﬁes it, and (2) any contained program within a program that speciﬁes the clause.

1.3.2.8 Interpreting Messages from the Compiler

If there are errors in your source ﬁle when you compile your program, the Compaq COBOL compiler ﬂags these errors and displays helpful messages. You can reference the message, locate the error, and, if necessary, correct the error in your program.

The general format of compiler messages shown on your screen is shown in the following example:

..........................^

%COBOL-s-ident, message-text

At line number n in name

%COBOL

The facility or program name of the Compaq COBOL compiler. This preﬁx indicates that the Compaq COBOL compiler issued the message.

The severity of the error, represented in the following way:

F Fatal error. The compiler does not produce an object module. You must correct the

E Error. The compiler makes an assumption about what you intended and continues.

W Warning. The compiler attempts to correct the error in the statement, but you

I Informational. This message usually appears with other messages to inform you of

error before you can compile the program to produce an object module.

However, the compiler’s assumption may not relate to your intention. Correct the error.

should verify that the compiler’s action is acceptable. Otherwise, your program may produce unexpected results.

speciﬁc actions taken by the compiler. No action is necessary on your part. Note that these messages are suppressed by default. You must invoke /WARN=ALL or /WARN=INFO to enable them.

ident

The message identiﬁcation. This is a descriptive abbreviation of the message text.

1–36 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

message-text

The compiler’s message. In many cases, it consists of no more than one line of output. A message generally provides you with enough information to determine the cause of the error so that you can correct it.

At line number n in name

The integer n is the number of the line where the diagnostic occurs. The number is relative to the beginning of the ﬁle or text library module speciﬁed by name.

A sample compiler message with two diagnostics looks like this in the listing ﬁle:

12 PROCEDURE DIVISION. 13 P-NAME 14 MOVE ABC TO XYZ.

................^

%COBOL-E-NODOT, Missing period is assumed

14 MOVE ABC TO XYZ.

............................^

%COBOL-F-UNDEFSYM, Undefined name

In the sample, the ﬁrst diagnostic pointer (^) points to the MOVE statement in source line number 14, which is the closest approximation to where the error (P-NAME is not followed by a period) occurred. The second diagnostic pointer points to XYZ, an undeﬁned name in source line number 14. Each diagnostic pointer is followed by a message line that identiﬁes, in this order:

• The Compaq COBOL compiler generated the message

• The severity code of the message

• The message identiﬁcation (a mnemonic of the message text)

• The text of the message Although most compiler messages are self-explanatory, some require additional

explanation. The online HELP facility for Compaq COBOL contains a list and descriptions of these Compaq COBOL compiler messages. Use the HELP COBOL Compiler Messages command to access this list.

To examine messages that occurred during compilation, you can search for each occurrence of %COBOL in the compiler listing ﬁle. Section 1.3.2.9 describes listing ﬁles.

The severity levels, and what you should do next, are as follows:

Severe The compiler does not produce an object module. You must correct the

Error The compiler makes an assumption about what you intended and

Warning The compiler attempts to correct the error in the statement, but you

Informational This message usually appears with other messages to inform you of

error before you can compile the program to produce an object module.

continues. However, the compiler’s assumption may not relate to your intention. Correct the error.

should verify that the compiler’s action is acceptable. Otherwise, your program may produce unexpected results.

speciﬁc actions taken by the compiler. No action is necessary on your part.

Developing Compaq COBOL Programs 1–37

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

1.3.2.9 Using Compiler Listing Files

A compiler listing ﬁle provides information that can help you debug or document your Compaq COBOL program. It consists of the following sections:

• Program listing The program listing section contains the source code plus line numbers

generated by the compiler. Any diagnostics will appear in this section.

• Storage map The storage map section is optional (produced by the /MAP qualiﬁer); it

contains summary information on program sections, variables, and arrays.

• Compilation summary The compilation summary section lists the qualiﬁers used with the COBOL

command and the compilation statistics.

• Machine code The machine code section is optional; it displays compiler-generated object

code.

To generate a listing ﬁle, specify the /LIST qualiﬁer when you compile your Compaq COBOL program interactively as in the following example for PROG_1.COB:

$ COBOL/LIST PROG_1.COB

If you compile your program as a batch job, the compiler creates a listing ﬁle by default. You can specify the /NOLIST qualiﬁer to suppress creation of the listing ﬁle, if that suits your purposes. (In either case, however, the listing ﬁle is not automatically printed.) By default, the name of the listing ﬁle is the name of your source ﬁle followed by the ﬁle type .LIS. You can include a ﬁle speciﬁcation with the /LIST qualiﬁer to override this default.

When used with the /LIST qualiﬁer, the following COBOL command qualiﬁers supply additional information in the compiler listing ﬁle:

• /COPY_LIST—Includes source statements speciﬁed by the COPY command.

• /CROSS_REFERENCE—Creates a cross-reference listing of user-deﬁned names and references.

• /MACHINE_CODE—Includes a list of compiler-generated machine code.

• /MAP—Produces maps, data names, procedure names, ﬁle names, and external references.

For a description of each qualiﬁer’s function, invoke the online HELP facility for COBOL at the system prompt as follows:

$ HELP COBOL

Compiler Listing File for a Contained Program

A contained COBOL program listing ﬁle includes two additional program elements that provide nesting level information about the main program and the contained program. For additional information about contained programs, see Chapter 12, Interprogram Communication.

1–38 Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

1.3.3 Linking a Compaq COBOL Program

After you compile a Compaq COBOL source program or module, use the LINK command to combine your object modules into one executable image that the OpenVMS Alpha operating system can execute. A source program or module cannot run until it is linked.

When you execute the LINK command, the OpenVMS Alpha Linker performs the following functions:

• Resolves local and global symbolic references in the object code

• Assigns values to the global symbolic references

• Signals an error message for any unresolved symbolic reference

• Allocates virtual memory space for the executable image The LINK command produces an executable image by default. However, you

can specify qualiﬁers and qualiﬁer options with the LINK command to obtain shareable images and system images.

See Table 1–5 for a list of commonly used LINK command qualiﬁers. For a complete list and for more information about the LINK qualiﬁers, invoke the online HELP facility for the LINK command at the system prompt.

Developing Compaq COBOL Programs

For a complete discussion of linker capabilities and for detailed descriptions of LINK qualiﬁers and qualiﬁer options, see the OpenVMS Linker Utility Manual.

1.3.3.1 The LINK Command

The format of the LINK command is as follows:

LINK[/qualiﬁer] ... {ﬁle-spec[/qualiﬁer] ...} ...

/qualiﬁer...

Speciﬁes output ﬁle options when it is positioned after the LINK command. Speciﬁes input ﬁle options when it is positioned after ﬁle-spec.

ﬁle-spec...

Speciﬁes the input ﬁles to be linked. If you specify more than one input ﬁle, you must separate the input ﬁle

speciﬁcations with a plus sign (+) or a comma (,). By default, the linker creates an output ﬁle with the name of the ﬁrst input

ﬁle speciﬁed and the ﬁle type EXE. If you link multiple ﬁles, specify the ﬁle containing the main program ﬁrst. Then the name of your output ﬁle will have the same name as your main program module.

The following command line links the object ﬁles MAINPROG.OBJ, SUBPROG1.OBJ, and SUBPROG2.OBJ to produce one executable image called MAINPROG.EXE:

$ LINK MAINPROG, SUBPROG1, SUBPROG2

Developing Compaq COBOL Programs 1–39

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

1.3.3.2 LINK Qualiﬁers

LINK qualiﬁers allow you to control various aspects of the link operation such as modifying linker input and output and invoking the debugging and traceback facilities.

Table 1–5 summarizes some of the more commonly used LINK qualiﬁers. Refer to the OpenVMS Linker Utility Manual for a complete list and explanations of the LINK qualiﬁers or invoke the online HELP facility for the LINK command at the OpenVMS Alpha prompt.

Note

Table 1–5 Commonly Used LINK Qualiﬁers

Function Qualiﬁer Default

Indicate that an input ﬁle is a library ﬁle.

Indicate that an input ﬁle is a linker options ﬁle.

Request output ﬁle, deﬁne a ﬁle speciﬁcation, and specify whether the image is shareable.

Request and specify the contents of an image map (memory allocation) listing.

Specify the amount of debugging information.

/LIBRARY Not applicable.

/OPTIONS Not applicable.

/EXECUTABLE[=ﬁle-spec] /SHAREABLE[=ﬁle-spec]

/BRIEF /[NO]CROSS_REFERENCE /FULL /MAP[=ﬁle-spec] or /NOMAP

/DEBUG[=ﬁle-spec] or /NODEBUG /[NO]TRACEBACK

/EXECUTABLE=

name.EXE

where name is the name of the ﬁrst input ﬁle. /NOSHAREABLE

/NOCROSS_REFERENCE /NOMAP (interactive) /MAP=name.MAP (batch)

where name is the name of the ﬁrst input ﬁle.

/NODEBUG /TRACEBACK

1.3.3.3 Specifying Modules Other than Compaq COBOL Modules

When you link Compaq COBOL modules with other modules, your application will not work correctly if a non Compaq COBOL module contains a LIB$INITIALIZE routine that:

1. Is invoked before the Compaq COBOL LIB$INITIALIZE routine (COB_ NAME_START) and

1–40 Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

2. Calls a Compaq COBOL program that contains CALL by data name, extended ACCEPT, or extended DISPLAY statements.

Compaq COBOL uses the LIB$INITIALIZE routine, COB_NAME_START, to initialize the run-time environment for the CALL by data name and extended ACCEPT and DISPLAY statements. Therefore, the COB_NAME_START routine must be invoked before any CALL, ACCEPT, or DISPLAY statements are performed.

The order in which LIB$INITIALIZE routines are invoked is determined during the link and is shown in the image map. To ensure that the Compaq COBOL LIB$INITIALIZE routine is invoked ﬁrst, change your link command to the following:

$ LINK/EXE=name SYS$SHARE:STARLET/INCL=COB_NAME_START,your_modules...

See Appendix B for information on a problem with LIB$INITIALIZE when you call a C program.

1.3.3.4 Specifying Object Module Libraries

Linking against object modules allows your program to access data and routines outside of your compilation units. You can create your own object module libraries or they can be supplied by the system.

Developing Compaq COBOL Programs

User-Created Object Module Libraries

You can make program modules accessible to other programmers by storing them in object module libraries. To link modules contained in an object module

library, use the /INCLUDE qualiﬁer with the LINK command

and specify the modules you want to link. The following example links the subprogram modules EGGPLANT, TOMATO, BROCCOLI, and ONION (contained in the VEGETABLES library) with the main program module GARDEN:

$ LINK GARDEN, VEGETABLES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)

An object module library also contains a symbol table with the names of the global symbols in the library, and the names of the modules in which the symbols are deﬁned. You specify the name of the object module library containing these symbol deﬁnitions with the /LIBRARY qualiﬁer. When you use the /LIBRARY qualiﬁer during a linking operation, the linker searches the speciﬁed library for all unresolved references found in the included modules during compilation.

The following example uses the library RACQUETS to resolve undeﬁned symbols in the BADMINTON, TENNIS, and RACQUETBALL libraries:

$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY

For more information about the /INCLUDE and /LIBRARY qualiﬁers, invoke the online HELP facility for the LINK command at the DCL prompt or refer to the OpenVMS Linker Utility Manual.

You can deﬁne one or more of your private object module libraries as default user libraries. The following section describes how to accomplish this using the DEFINE command.

The /INCLUDE qualiﬁer on the LINK command is not to be confused with the /INCLUDE qualiﬁer on the COBOL compile command, which speciﬁes a search list for COPY ﬁles.

Developing Compaq COBOL Programs 1–41

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Deﬁning Default User Object Module Libraries

You can deﬁne one or more of your private object module libraries as your default user libraries using the DCL DEFINE command, as in the following example:

$ DEFINE LNK$LIBRARY DEFLIB

The linker searches default user libraries for unresolved references after it searches modules and libraries speciﬁed in the LINK command.

In this example, LNK$LIBRARY is a logical name and DEFLIB is the name of an object module library (having the ﬁle type OLB) that you want the linker to search automatically in all subsequent link operations.

You can establish any object module library as a default user library by creating a logical name for the library. The logical names you must use are LNK$LIBRARY (as in the preceding example), LNK$LIBRARY_1, LNK$LIBRARY_2, and so on, to LNK$LIBRARY_999. When more than one of these logical names exists when a LINK command executes, the linker searches them in numeric order beginning with LNK$LIBRARY.

When one or more logical names exist for default user libraries, the linker uses the following search order to resolve references:

• The process, group, and system logical name tables (in that order) are searched for the name LNK$LIBRARY. If the logical name exists in any of these tables and if it contains the desired reference, the search is ended.

• The process, group, and system logical name tables (in that order) are searched for the name LNK$LIBRARY_1. If the logical name exists in any of these tables, and if it contains the desired reference, the search is ended.

This search sequence occurs for each reference that remains unresolved.

System-Supplied Object Module Libraries

All Compaq COBOL programs reference system-supplied object module libraries when they are linked. These libraries contain routines that provide

I/O and other system functions. Additionally, you can use your own libraries to provide application-speciﬁc object modules.

To use the contents of an object module library, you must do the following:

• Refer to a symbol in the object module by name in your program in a CALL statement or VALUE EXTERNAL reference.

• Make sure that the linker can locate the library that contains the object module by ensuring that required software is correctly installed.

• Make sure that your default directory (or LINK/EXE directory) is valid and that you have write privileges to it.

To specify that a linker input ﬁle is a library ﬁle, use the /LIBRARY qualiﬁer. This qualiﬁer causes the linker to search for a ﬁle with the name you specify and the default ﬁle type .OLB. If you specify a ﬁle that the linker cannot locate, a fatal error occurs and linking terminates.

The sections that follow describe the order in which the linker searches libraries that you specify explicitly, default user libraries, and system libraries.

For more information about object module libraries, see the OpenVMS Linker Utility Manual.

1–42 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Deﬁning the Search Order for Libraries

When you specify libraries as input for the linker, you can specify as many as you want; there is no practical limit. More than one library can contain a deﬁnition for the same module name. The linker uses the following conventions to search libraries speciﬁed in the command string:

• A library is searched only for deﬁnitions that are unresolved in the previously speciﬁed input ﬁles.

• If you speciﬁed more than one object module library, the libraries are searched in the order in which they are speciﬁed.

For example:

$ LINK METRIC,DEFLIB/LIBRARY,APPLIC

The library DEFLIB will be searched only for unresolved references in the object module METRIC. It is not searched to resolve references in the object module APPLIC. However, this command can also be entered as follows:

$ LINK METRIC,APPLIC,DEFLIB/LIBRARY

In this case, DEFLIB.OLB is searched for all references that are not resolved between METRIC and APPLIC. After the linker has searched all libraries speciﬁed in the command, it searches default user libraries, if any, and then the default system libraries.

1.3.3.5 Creating Shareable Images

You can create Compaq COBOL programs as shareable images by using the LINK qualiﬁer /SHARE. A shareable image is a single copy of a program that can be shared by many users or applications. Using shareable images provides the following beneﬁts:

• Saves system resources, since one physical copy of a set of procedures can be shared by more than one application or user

• Facilitates the linking of very large applications by allowing you to break down the whole application into manageable segments

• Allows you to modify one or more sections of a large application without having to relink the entire program

The following list describes one way to create and install a Compaq COBOL program as a shareable image:

1. Create the main program used to call the subprogram (as a shareable image).

2. Create the subprogram.

3. Link the shareable image program using the /SHARE qualiﬁer and including the options ﬁle containing the symbol vector in the LINK command as an input ﬁle. (Refer to Using Symbol Vectors with Shareable Images in this section for information about declaring universal symbols using a symbol vector.)

4. Deﬁne a logical name to point to your shareable image.

5. Link the main program with the shareable image.

Once you have completed these steps, you can run the main program to access the subprogram installed as a shareable image.

Developing Compaq COBOL Programs 1–43

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

See the OpenVMS Linker Utility Manual and the Guide to Creating OpenVMS Modular Procedures for more information about shareable images.

The following sample programs and command procedure provide an example of how to create, link, and install a subprogram as a shareable image, as described in the preceding steps.

Example 1–2 shows the main program CALLER.COB and the two subprograms (SUBSHR1.COB and SUBSHR2.COB). Only the subprograms are installed as shareable images.

1–44 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Example 1–2 Main Program and Subprograms

* CALLER.COB IDENTIFICATION DIVISION. PROGRAM-ID. CALLER. ****************************************************************** * This program calls a subprogram installed as a shareable image.* ****************************************************************** PROCEDURE DIVISION.

CALL "SUBSHR1"

ON EXCEPTION

END-CALL. STOP RUN.

END PROGRAM CALLER. * SUBSHR1.COB

IDENTIFICATION DIVISION. PROGRAM-ID. SUBSHR1.

****************************************************************** * This program is linked as a shareable image. When it is called,* * it calls another program installed as a shareable image. * ****************************************************************** PROCEDURE DIVISION.

DISPLAY "Call to SUBSHR1 successful. Calling SUBSHR2.". CALL "SUBSHR2"

END-CALL.

END PROGRAM SUBSHR1.

DISPLAY "First CALL failed. Program aborted."

ON EXCEPTION

DISPLAY "Second call failed. Control returned to CALLER."

* SUBSHR2.COB IDENTIFICATION DIVISION. PROGRAM-ID. SUBSHR2. **************************************************************** * This program is linked as a shareable image and is called by * * another shareable image. * **************************************************************** PROCEDURE DIVISION.

DISPLAY "Call to SUBSHR2 successful!".

END PROGRAM SUBSHR2.

Example 1–3 shows a command procedure that compiles, links, and installs the sample programs in Example 1–2.

Example 1–3 Command Procedure to Link a Program as a Shareable Image

$! Create the main program and subprograms to be installed as $! shareable images. In this example CALLER.COB is the main program. $! SUBSHR1.COB and SUBSHR2.COB are the subprograms to be installed $! as shareable images. $!

(continued on next page)

Developing Compaq COBOL Programs 1–45

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

Example 1–3 (Cont.) Command Procedure to Link a Program as a Shareable

Image

$! Compile the main program and subprograms. $! $ COBOL CALLER.COB $ COBOL SUBSHR1.COB $ COBOL SUBSHR2.COB $! $! Create an options file containing all the universal symbols $! (entry points and other data symbols) for the subprograms. $! $ COPY SYS$INPUT OPTIONS1.OPT $ DECK

SYMBOL_VECTOR=(SUBSHR1=PROCEDURE,SUBSHR2=PROCEDURE) $ EOD $! $! Link the subprograms using the /SHARE qualifier to the $! shareable library and the options file. For more information $! on options files, refer to the OpenVMS Linker Utility Manual. $! $ LINK/SHARE=MYSHRLIB SUBSHR1,SUBSHR2,OPTIONS1/OPT $! $! Assign a logical name for the shareable images. $! $ ASSIGN DEVICE:[DIRECTORY]MYSHRLIB.EXE MYSHRLIB $! $! Create a second options file to map the main program to the $! shareable image library. $! $ COPY SYS$INPUT OPTIONS2.OPT $ DECK

MYSHRLIB/SHAREABLE $ EOD

$! $! Link the main program with the shareable image subprograms $! through the options file. $! $ LINK CALLER,OPTIONS2/OPT $! $! Now you can run the main program.

Using Symbol Vectors with Shareable Images

To make symbols in the shareable image available for other modules to link against, you must declare the symbols as universal. You declare universal symbols by creating a symbol vector. You create a symbol vector by specifying the SYMBOL_VECTOR=option clause in a linker options ﬁle. List all of the symbols you want to be universal in the order in which you want them to appear in the symbol vector.

If you use symbol vectors, you can modify the contents of shareable images and avoid relinking user programs bound to the shareable image when you modify the image. Once you have created the symbol vector, you can install the subprograms and link the main program to the shareable library. Symbol vectors, if used according to the coding conventions, can also provide upward compatibility.

For more information about symbol vectors, refer to the OpenVMS Linker Utility Manual.

1–46 Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

1.3.3.6 Interpreting Messages from the Linker

If the linker detects any errors while linking object modules, it displays system messages indicating their cause and severity. If any error or fatal error conditions occur, the linker does not produce an image ﬁle. See the OpenVMS Linker Utility Manual for complete information about the format of linker options.

Linker messages are self-explanatory; you do not usually need additional information to determine the speciﬁc error.

Common Linking Errors to Avoid

The following are some common errors to avoid when linking COBOL programs:

• Trying to link a module that produced warning or error messages during compilation. Although you can usually link compiled modules for which the compiler generated system messages, you should verify that the modules actually produce the expected output during program execution.

• Forgetting to specify a ﬁle type for an input ﬁle that has a ﬁle type other than the default on the command line. The linker searches for a ﬁle that has a ﬁle type .OBJ by default. When the linker cannot locate an object ﬁle and you have not identiﬁed your input ﬁle with the appropriate ﬁle type, the linker signals an error message and does not produce an image ﬁle.

Developing Compaq COBOL Programs

• Trying to link a nonexistent module. The linker signals an error message if you misspell a module name on the command line or if the compilation contains fatal messages.

• Omitting required module or library names from the command line. The linker cannot locate the deﬁnition for a speciﬁed global symbol reference.

Consider, for example, the following LINK command for a main program module, OCEAN.OBJ, that calls the subprograms REEF, SHELLS, and SEAWEED:

$ LINK OCEAN,REEF,SHELLS

If the routine SEAWEED.OBJ does not exist in the directory from which the command is issued, an error occurs and the linker issues the following diagnostic messages:

%LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, undefined symbol SEAWEED referenced

%LINK-W-USEUNDEF, undefined symbol SEAWEED referenced

If an error occurs when you link modules, you can often correct it by reentering the command string and specifying the correct modules or libraries.

For a complete list of linker options, see the OpenVMS System Messages and Recovery Procedures Reference Manual.

in psect $CODE offset %X0000000C in module OCEAN file DEVICE$:[COBOL.EXAMPLES]PROG.OBJ;1

in psect $CODE offset %X00000021 in module OCEAN file DEVICE$:[COBOL.EXAMPLES]PROG.OBJ;1

Developing Compaq COBOL Programs 1–47

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

1.3.4 Running a Compaq COBOL Program

After you compile and link your program, use the RUN command to execute it. In its simplest form the RUN command has the following format:

$ RUN myprog

In the preceding example MYPROG.EXE is the ﬁle speciﬁcation of the image you want to run. If you omit the ﬁle type from the ﬁle speciﬁcation, the system automatically provides a default value. The default ﬁle type is .EXE. If you omit a path speciﬁcation, the system will expect MYPROG.EXE to be in the current directory.

When you run your application it makes calls to the Compaq COBOL RunTime Library (RTL) installed on your system. If your application is run on a system other than the one where the application was compiled, there are two requirements that must be met:

• The Compaq COBOL Run-Time Library must be installed.

• The RTL version must match (or be higher than) the version of the RTL on the system where the application was compiled. Otherwise, the system displays a diagnostic message each time you run the application.

1.3.4.1 Accessing Command-Line Arguments at Run Time

Your Compaq COBOL programs can read command-line arguments and access (read and write) system logicals. Command-line arguments enable you to provide information to a program at run time. Your program provides the logic to parse the command line, identify command-line options, and act upon them. For example, you might develop a program named MYPROG that will extract a given amount of data from a speciﬁed ﬁle, where both the number of records to read and the ﬁle name are highly dynamic, changing for each activation of your program. In this case your program would contain code that reads a commandline argument for the number of records to read and a second argument for the ﬁle speciﬁcation.

To run the program with command-line arguments, you must deﬁne it as a foreign command, as follows:

$ MYPROG :== "$device:[dir]MYPROG.EXE"

When you use this command, you will replace device and dir with the valid device:[dir] names where MYPROG.EXE is located. Your program execution command could then look like the following:

$ MYPROG 1028 POWERS.DAT

In this hypothetical case, the program MYPROG would read 1,028 records from the ﬁle POWERS.DAT.

Multiple command-line arguments are delimited by spaces, as shown in the preceding example. If an argument itself contains spaces, enclose that argument in quotation marks (" ") as follows:

$ myprog2 "all of this is argument 1" argument2

In this example the returned value of argument1 will be the entire string ‘‘all of this is argument1’’, and argument2 will be simply ‘‘argument2’’.

1–48 Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

You provide deﬁnitions for the command-line arguments with the SPECIAL-NAMES paragraph in your program’s Environment Division, and include ACCEPT and DISPLAY statements in the Procedure Division to parse the command line and access the arguments. Detailed information about commandline argument capability is in the ACCEPT and DISPLAY sections in the Compaq COBOL Reference Manual.

1.3.4.2 Accessing System Logicals at Run Time

You can read and write system logicals at run time through your Compaq COBOL program.

Example 1–4 allows the user to specify a ﬁle speciﬁcation by putting the directory in the value of the logical COBOLPATH and the ﬁle name in a command-line argument.

Example 1–4 Accessing Logicals and Command-Line Arguments

IDENTIFICATION DIVISION. PROGRAM-ID. EXAMPLE. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES.

SYSERR IS STANDARD-ERROR ENVIRONMENT-NAME IS NAME-OF-LOGICAL ENVIRONMENT-VALUE IS LOGICAL-VALUE ARGUMENT-NUMBER IS POS-OF-COMMAND-LINE-ARGUMENT

ARGUMENT-VALUE IS COMMAND-LINE-ARGUMENT. DATA DIVISION. WORKING-STORAGE SECTION. 01 howmany-records PIC 9(5). 01 env-dir PIC x(50). 01 file-name PIC x(50). 01 file-spec PIC x(100). BEGIN.

ACCEPT howmany-records FROM COMMAND-LINE-ARGUMENT

ON EXCEPTION

DISPLAY "No arguments specified"

UPON STANDARD-ERROR

STOP RUN

END-ACCEPT.

DISPLAY "COBOLPATH" UPON NAME-OF-LOGICAL.

ACCEPT env-dir FROM LOGICAL-VALUE

ON EXCEPTION

DISPLAY "Logical COBOLPATH is not set"

UPON STANDARD-ERROR

END-DISPLAY ACCEPT file-name FROM COMMAND-LINE-ARGUMENT

ON EXCEPTION

DISPLAY "Attempt to read beyond end of command line"

UPON STANDARD-ERROR

END-DISPLAY

NOT ON EXCEPTION

STRING env-dir file-name delimited by " " into file-spec DISPLAY "Would have read " howmany-records " records from " file-spec

END-ACCEPT

END-ACCEPT.

Developing Compaq COBOL Programs

Example 1–4 assumes that the logical COBOLPATH is set as follows:

$ define COBOLPATH MYDEV:[MYDIR]

Developing Compaq COBOL Programs 1–49

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

When you execute the following command line:

$ MYPROG 1028 powers.dat

The following will result:

• howmany–records will contain 1028.

• ﬁle-path will contain MYDEV:[MYDIR]

• ﬁle-name will contain powers.dat

• ﬁle-spec will contain MYDEF:[MYDIR]powers.dat For additional information, see the ACCEPT and DISPLAY statements in the

Compaq COBOL Reference Manual.

1.3.4.3 Accessing Input and Output Devices at Run Time

ACCEPT and DISPLAY statements may interact with the input and output devices by referring to them through the environment variables COBOL_INPUT and COBOL_OUTPUT, respectively. See Chapter 11 for more information.

1.3.4.4 Debugging Environment

Perhaps the most common qualiﬁer added to the RUN command line is DEBUG. The form of the RUN command with DEBUG is as follows:

RUN [/[NO]DEBUG] ﬁle-spec

In the preceding syntax format ﬁle-spec is the name of the executable image to be run. A typical example would be:

$ RUN /DEBUG MYPROG

In this example, MYPROG is the name of the executable image to be run. You would specify the /DEBUG qualiﬁer to invoke the OpenVMS Debugger if the image was not linked with it. You cannot use /DEBUG on images linked with the /NOTRACEBACK qualiﬁer. If the image (in this case, MYPROG) was linked with the /DEBUG qualiﬁer and you do not want the debugger to prompt you, use the /NODEBUG qualiﬁer. The default action depends on whether or not the ﬁle was linked with the /DEBUG qualiﬁer.

Note

Using the /DEBUG qualiﬁer with the RUN command does not produce symbol table information if you did not specify the /DEBUG qualiﬁer when you compiled and linked your program.

The following example executes the image MYPROG.EXE without invoking the debugger:

$ RUN MYPROG/NODEBUG

See Appendix C for more information about debugging programs.

1–50 Developing Compaq COBOL Programs

1.3.4.5 Interpreting Run-Time Messages

During execution, an image can generate a fatal error called an exception condition. When an exception condition occurs, the system displays a message.

Run-time messages can also be issued by the OpenVMS Alpha operating system or by other utilities such as SORT. Other kinds of errors that can occur at run time include program run errors and run-time input/output errors.

Run-time messages have the following format:

%COB-s-ident, message-text

%COB

The program name of the Compaq COBOL Run-Time Library. This preﬁx indicates a run-time message.

The severity of the error. As with messages from the compiler and the linker, the severity indicator can be F (Fatal), E (Error), W (Warning), or I (Informational).

ident

The message identiﬁcation. This is a descriptive abbreviation of the message text.

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

message-text

The run-time message. This portion may contain more than one line of output. A message generally provides you with enough information to determine the cause of the error so that you can correct it.

The following example shows a run-time message issued for an illegal divide:

%COB-E-DIVBY-ZER, divide by zero; execution continues

Both the compiler and the OpenVMS Alpha Run-Time Library include facilities for detecting and reporting errors. You can use the OpenVMS Debugger and the traceback facility to help you locate errors that occur during program execution. For a description of Compaq COBOL run-time messages, use the HELP COBOL Run-Time Messages command.

Run-Time Messages

Faulty program logic can cause abnormal termination. If errors occur at run time, the Run-Time Library (RTL) displays a message with the same general format as system error messages. In addition, the system traceback facility displays a list of the routines that were active when the error occurred.

When an error occurs, TRACEBACK produces a symbolic dump of the active call frames. A call frame represents one execution of a routine. For each call frame, TRACEBACK displays the following information:

1. The module name, (program-id)

2. The routine name (program-id)

3. The source listing line number where the error or CALL occurred

4. Program-counter (PC) information You can also use the OpenVMS Debugger to examine the machine code

instruction. To do this, compile and link the program using the /DEBUG qualiﬁer. When you run the program, you automatically enter the debugger. Once in the debugger, you could use the EXAMINE/INSTRUCTION command to examine the contents of the failed instruction. You could also use the debugger in screen mode, which would indicate where the error occurred.

Developing Compaq COBOL Programs 1–51

Developing Compaq COBOL Programs

1.3 Developing Programs on OpenVMS Alpha

For more information about the OpenVMS Debugger, refer to Appendix C and the OpenVMS Debugger Manual.

1.4 Program Run Messages

Incorrect or undesirable program results are usually caused by data errors or program logic errors. You can resolve most of these errors by desk-checking your program and by using a debugger.

1.4.1 Data Errors

Faulty or incorrectly deﬁned data often produce incorrect results. Data errors can sometimes be attributed to one or more of the following actions:

• Incorrect picture size. As shown in the following sample of a partial program, if the picture size of a receiving data item is too small, your data may be truncated:

77 COUNTER PIC S9.

. . .

PROCEDURE DIVISION.

. . .

LOOP.

ADD 1 TO COUNTER IF COUNTER < 10 GO TO LOOP.

The IF clause will produce an inﬁnite loop because of the one-digit size limit of COUNTER, which is PIC S9. If COUNTER were PIC S99, or if the clause used 9 instead of 10, the condition could be false, causing a proper exit from the loop.

• Incorrect record ﬁeld position. The record ﬁeld positions that you specify in your program may not agree with a ﬁle’s record ﬁeld positions. For example, a ﬁle could have this record description:

01 PAY-RECORD.

03 P-NUMBER PIC X(5). 03 P-WEEKLY-AMT PIC S9(5)V99 COMP-3. 03 P-MONTHLY-AMT PIC S9(5)V99 COMP-3. 03 P-YEARLY-AMT PIC S9(5)V99 COMP-3.

. . .

Incorrectly positioning these ﬁelds can produce faulty data.

In the following example, a program references the ﬁle incorrectly. The ﬁeld described as P-YEARLY-AMT actually contains P-MONTHLY-AMT data, and vice versa.

1–52 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.4 Program Run Messages

01 PAY-RECORD.

03 P-NUMBER PIC X(5). 03 P-WEEKLY-AMT PIC S9(5)V99 COMP-3. 03 P-YEARLY-AMT PIC S9(5)V99 COMP-3. 03 P-MONTHLY-AMT PIC S9(5)V99 COMP-3.

. .

PROCEDURE DIVISION. ADD-TOTALS.

You can minimize record ﬁeld position errors by writing your ﬁle and record descriptions in a library ﬁle and then using the COPY statement in your programs. On OpenVMS Alpha systems, you can also use the COPY FROM DICTIONARY statement.

Choosing your test data carefully can minimize faulty data problems. For instance, rather than using actual or ideal data, use test ﬁles that include data extremes.

Determining when a program produces incorrect results can often help your debugging effort. You can do this by maintaining audit counts (such as total master in = nnn, total transactions in = nnn, total deletions = nnn, total master out = nnn) and displaying the audit counts when the program ends. Using conditional compilation lines (see Section 1.3.2.7) in your program can also help you to debug it.

ADD P-MONTHLY-AMT TO TOTAL-MONTHLY-AMT.

. . .

1.4.2 Program Logic Errors

When checking your program for logic errors, ﬁrst examine your program for some of the more obvious bugs, such as the following:

• Hidden periods. Periods inadvertently placed in a statement usually produce unexpected results. For example:

050-DO-WEEKLY-TOTALS.

IF W-CODE = "W"

PERFORM 100-WEEKLY-SUMMARY ADD WEEKLY-AMT TO WEEKLY-TOTALS. GO TO 000-READ-A-MASTER.

WRITE NEW-MASTER-REC.

The period at the end of ADD WEEKLY-AMT TO WEEKLY-TOTALS terminates the scope of the IF statement and changes the logic of the program. Including the extra period before the GO TO statement transforms GO TO 000-READ-A-MASTER from a conditional statement to an unconditional statement. Because the GO TO statement is not within the scope of the IF statement, it will always be executed. In addition, the WRITE statement following the GO TO will never be executed.

• Tests for equality, which can cause an inﬁnite loop if the procedure is to be executed until the test condition is met, for example:

* This is a test for equality PERFORM ABC-ROUTINE UNTIL A-COUNTER = 10.

Developing Compaq COBOL Programs 1–53

Developing Compaq COBOL Programs

1.4 Program Run Messages

If, during execution, the program increments A-COUNTER by a value other than 1 (2 or 1.5, for example), A-COUNTER may never equal 10, causing a loop in ABC-ROUTINE. You can prevent this type of error by changing the statement to something like this:

* This is a test for inequality PERFORM ABC-ROUTINE UNTIL A-COUNTER > 9

• Testing two ﬂoating point numbers (for example, COMP-1 and COMP-2 ﬁelds) for equality. The calculations of your program might never produce exact numerical equality between two ﬂoating point values.

• Two negative test conditions combined with an OR. The object of the following statement is to execute GO TO 200-PRINT-REPORT when TEST-FIELD contains other than an A or B. However, the GO TO always executes because no matter what TEST-FIELD contains, one of the conditions is always true.

IF TEST-FIELD NOT = "A" OR NOT = "B"

GO TO 200-PRINT-REPORT. . . .

The following statement does not contain the logic error:

IF TEST-FIELD NOT = "A" AND NOT = "B"

GO TO 200-PRINT-REPORT. . . .

1.4.3 Run-Time Input/Output Errors

An input/output error is a condition that causes an I/O statement to fail. These I/O errors are detected at run time by the I/O system. Each time an I/O operation occurs, the I/O system generates a two-character ﬁle status value. One way to determine the nature of an I/O error is to check a ﬁle’s I/O status by using ﬁle status data items. (See the Compaq COBOL Reference Manual for a list of ﬁle status values.) See Chapter 7, Handling Input/Output Exception Conditions for additional information about I/O exception condition handling.

Checking a ﬁle’s I/O status within a Declarative USE procedure or in an INVALID KEY imperative condition can help you determine the nature of an I/O error. For example:

FD INDEXED-MASTER

ACCESS MODE IS DYNAMIC FILE STATUS IS MASTER-STATUS

RECORD KEY IN IND-KEY. . . .

WORKING-STORAGE SECTION. 01 MASTER-STATUS PIC XX VALUE SPACES.

. . .

PROCEDURE DIVISION.

. . .

1–54 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.4 Program Run Messages

050-READ-MASTER.

READ INDEXED-MASTER

INVALID KEY PERFORM 100-CHECK-STATUS GO TO 200-INVALID-READ. . . .

100-CHECK-STATUS.

IF MASTER-STATUS = "23"

DISPLAY "RECORD NOT IN FILE".

IF MASTER-STATUS = "24"

DISPLAY "BOUNDARY VIOLATION OR RELATIVE RECORD

NUMBER TOO LARGE". . . .

If your program contains a Declarative USE procedure for a ﬁle and an I/O operation for that ﬁle fails, the I/O system performs the USE procedure, but does not display an error message.

A Declarative USE procedure can sometimes avoid program termination. For example, File Status 91 indicates that the ﬁle is locked by another program; rather than terminate your program, you can perform other procedures and then try reopening the ﬁle. If program continuation is not desirable, the Declarative USE procedure can perform housekeeping functions, such as saving data or displaying program-generated diagnostic messages.

If you specify an INVALID KEY phrase for a ﬁle and the I/O operation causes an INVALID KEY condition, the I/O system performs the associated imperative statement and no other ﬁle processing for the current statement. The Declarative USE procedure (if any) is not performed. The INVALID KEY phrase processes I/O errors due to invalid key conditions only.

If you do not specify an INVALID KEY phrase but declare a Declarative USE procedure for the ﬁle, the I/O system performs the Declarative USE procedure and returns control to the program.

If a severe error occurs and you do not have a Declarative Use procedure, your program will terminate abruptly with a run-time diagnostic. For example, given a program that looks for AFILE.DAT and that ﬁle is missing:

cobrtl: severe: file AFILE.DAT not found

In this case, program run ends because you have not handled the error with a Declarative Use procedure.

1.4.4 I/O Errors and RMS (OpenVMS)

I/O errors are detected by the I/O system, which (for OpenVMS Alpha systems) consists of Record Management Services (RMS) and the Run-Time Library (RTL). You can use the RMS special registers, which contain the primary and secondary RMS completion codes of an I/O operation, to detect errors. The RMS special registers are as follows:

RMS-STS RMS-STV RMS-FILENAME RMS-CURRENT-STS RMS-CURRENT-STV RMS-CURRENT-FILENAME

Developing Compaq COBOL Programs 1–55

Developing Compaq COBOL Programs

1.4 Program Run Messages

Refer to the Compaq COBOL Reference Manual and the OpenVMS Record Management Services Reference Manual for more information about RMS special

registers. Examples 1–5 and 1–6 show how you can use RMS special registers to detect

errors.

Example 1–5 Using RMS Special Registers to Detect Errors (OpenVMS)

IDENTIFICATION DIVISION. PROGRAM-ID. RMS-SPEC-REGISTERS. * * This program demonstrates the use of RMS special registers to * implement a different recovery for each of several errors with RMS files * ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT OPTIONAL EMP-FILE

ASSIGN TO "SYS$DISK:ART.DAT".

SELECT REPORT-FILE

ASSIGN TO "SYS$OUTPUT". DATA DIVISION. FILE SECTION. FD EMP-FILE

01 EMP-RECORD.

FD REPORT-FILE REPORT IS RPT. WORKING-STORAGE SECTION. 01 VAL-OF-ID PIC X(20). 01 END-OF-FILE PIC S9(9) COMP VALUE EXTERNAL RMS$_EOF. 01 BADNAME PIC S9(9) COMP VALUE EXTERNAL SS$_BADFILENAME. 01 FILE-NOT-FOUND PIC S9(9) COMP VALUE EXTERNAL RMS$_FNF. 01 DIR-NOT-FOUND PIC S9(9) COMP VALUE EXTERNAL RMS$_DNF. 01 INV-DEVICE PIC S9(9) COMP VALUE EXTERNAL RMS$_DEV. 01 INV-FILE-ID PIC S9(9) COMP VALUE EXTERNAL RMS$_IFI. 01 RMS-ERR PIC S9(9) COMP VALUE EXTERNAL SHR$_RMSERROR. 01 D-DATE PIC 9(6). 01 EOF-SW PIC X.

01 VAL-OP-SW PIC X.

01 OP PIC X.

VALUE OF ID IS VAL-OF-ID. 02 EMP-ID PIC 9(7).

02 EMP-NAME PIC X(15). 02 EMP-ADDRESS PIC X(30).

88 E-O-F VALUE "E". 88 NOT-E-O-F VALUE "N".

88 VALID-OP VALUE "V". 88 OP-FAILED VALUE "F".

88 OP-OPEN VALUE "O". 88 OP-CLOSE VALUE "C". 88 OP-READ VALUE "R".

1–56 Developing Compaq COBOL Programs

(continued on next page)

Developing Compaq COBOL Programs

1.4 Program Run Messages

Example 1–5 (Cont.) Using RMS Special Registers to Detect Errors (OpenVMS)

REPORT SECTION. RD RPT PAGE 26 LINES HEADING 1 FIRST DETAIL 5. 01 TYPE IS PAGE HEADING.

02 LINE IS PLUS 1.

03 COLUMN 1 PIC X(16) VALUE "Employee File on". 03 COLUMN 18 PIC Z9/99/99 SOURCE D-DATE.

02 LINE IS PLUS 2.

03 COLUMN 2 PIC X(5) VALUE "emp ". 03 COLUMN 22 PIC X(4) VALUE "name". 03 COLUMN 42 PIC X(7) VALUE "address".

01 REPORT-LINE TYPE IS DETAIL.

PROCEDURE DIVISION. DECLARATIVES. USE-SECT SECTION.

CHECK-RMS-SPECIAL-REGISTERS.

END DECLARATIVES. MAIN-PROG SECTION. 000-DRIVER.

03 COLUMN 70 PIC ZZ9 SOURCE PAGE-COUNTER.

02 LINE IS PLUS 1.

03 COLUMN IS 1 PIC 9(7) SOURCE EMP-ID. 03 COLUMN IS 20 PIC X(15) SOURCE IS EMP-NAME. 03 COLUMN IS 42 PIC X(30) SOURCE IS EMP-ADDRESS.

USE AFTER STANDARD ERROR PROCEDURE ON EMP-FILE. SET OP-FAILED TO TRUE.

EVALUATE RMS-STS OF EMP-FILE TRUE

WHEN (END-OF-FILE) OP-READ

SET VALID-OP TO TRUE

SET E-O-F TO TRUE WHEN (BADNAME) OP-OPEN WHEN (FILE-NOT-FOUND) OP-OPEN WHEN (DIR-NOT-FOUND) OP-OPEN WHEN (INV-DEVICE) OP-OPEN

DISPLAY "File cannot be found or file spec is invalid"

DISPLAY RMS-FILENAME OF EMP-FILE

DISPLAY "Enter corrected file (cntrl-z to STOP RUN): "

WITH NO ADVANCING

ACCEPT VAL-OF-ID AT END STOP RUN END-ACCEPT WHEN ANY OP-CLOSE

CONTINUE WHEN ANY RMS-STS OF EMP-FILE IS SUCCESS

SET VALID-OP TO TRUE WHEN OTHER

IF RMS-STV OF EMP-FILE NOT = ZERO

THEN

CALL "LIB$STOP" USING

BY VALUE RMS-STS OF EMP-FILE, BY VALUE RMS-STV OF EMP-FILE

ELSE

CALL "LIB$STOP" USING

BY VALUE RMS-STS OF EMP-FILE

END-IF

END-EVALUATE.

PERFORM 100-INITIALIZE. PERFORM WITH TEST AFTER UNTIL E-O-F

GENERATE REPORT-LINE

READ EMP-FILE END-PERFORM PERFORM 200-CLEANUP. STOP RUN.

(continued on next page)

Developing Compaq COBOL Programs 1–57

Developing Compaq COBOL Programs

1.4 Program Run Messages

Example 1–5 (Cont.) Using RMS Special Registers to Detect Errors (OpenVMS)

100-INITIALIZE.

ACCEPT D-DATE FROM DATE. DISPLAY "Enter file spec of employee file: " WITH NO ADVANCING. ACCEPT VAL-OF-ID. PERFORM WITH TEST AFTER UNTIL VALID-OP

SET VALID-OP TO TRUE SET OP-OPEN TO TRUE OPEN INPUT EMP-FILE IF OP-FAILED THEN

SET OP-CLOSE TO TRUE CLOSE EMP-FILE

END-IF END-PERFORM. OPEN OUTPUT REPORT-FILE. INITIATE RPT. SET NOT-E-O-F TO TRUE. SET OP-READ TO TRUE. READ EMP-FILE.

200-CLEANUP.

TERMINATE RPT. SET OP-CLOSE TO TRUE. CLOSE EMP-FILE REPORT-FILE.

END PROGRAM RMS-SPEC-REGISTERS.

Example 1–6 Using RMS-CURRENT Special Registers to Detect Errors

(OpenVMS)

IDENTIFICATION DIVISION. PROGRAM ID. RMS-CURRENT-SPEC-REGISTERS. * * This program demonstrates the use of RMS-CURRENT special registers * to implement a single recovery for RMS file errors with multiple files * ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT FILE-1

SELECT FILE-2 SELECT FILE-3

ASSIGN TO "SYS$DISK:ART_1.DAT".

ASSIGN TO "SYS$DISK:ART_2.DAT".

ASSIGN TO "SYS$DISK:ART_3.DAT".

(continued on next page)

1–58 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.4 Program Run Messages

Example 1–6 (Cont.) Using RMS-CURRENT Special Registers to Detect Errors

(OpenVMS)

DATA DIVISION. FILE SECTION. FD FILE-1. 01 FILE-1-REC.

FD FILE-2. 01 FILE-2-REC.

FD FILE-3. 01 FILE-3-REC.

PROCEDURE DIVISION. DECLARATIVES. USE-SECT SECTION.

CHECK-RMS-CURRENT-REGISTERS.

END DECLARATIVES. MAIN-PROG SECTION. MAIN-PARA.

END-PROGRAM RMS-CURRENT-SPEC-REGISTERS.

02 F1-REC-FIELD PIC 9(9).

02 F2-REC-FIELD PIC 9(9).

02 F3-REC-FIELD PIC 9(9).

USE AFTER STANDARD EXCEPTION PROCEDURE ON INPUT. DISPLAY "************** ERROR **************".

DISPLAY "Error on file: " RMS-CURRENT-FILENAME. DISPLAY "Status Values:". DISPLAY " RMS-STS = " RMS-CURRENT-STS WITH CONVERSION. DISPLAY " RMS-STV = " RMS-CURRENT-STV WITH CONVERSION. DISPLAY "***********************************".

OPEN INPUT FILE-1. OPEN INPUT FILE-2. OPEN INPUT FILE-3. . . . CLOSE FILE-1. CLOSE FILE-2. CLOSE FILE-3. STOP RUN.

♦

1.5 Using Program Switches

You can control program execution by deﬁning switches in your Compaq COBOL program and setting them internally (from within the image) or externally (from outside the image). Switches exist as the environment variable COBOL_SWITCHES (on the Tru64 UNIX operating system) or the logical name COB$SWITCHES (on the OpenVMS Alpha operating system).

On OpenVMS Alpha systems, switches can be deﬁned for the image, process, group, or system. ♦

On Tru64 UNIX systems, switches can be deﬁned for the image or process. ♦

Developing Compaq COBOL Programs 1–59

Developing Compaq COBOL Programs

1.5 Using Program Switches

1.5.1 Setting and Controlling Switches Internally

To set switches from within the image, deﬁne them in the SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION and use the SET statement in the PROCEDURE DIVISION to specify switches ON or OFF, as in the following example:

ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES.

SWITCH 10 IS MY-SWITCH

ON IS SWITCH-ON

OFF IS SWITCH-OFF. . . .

PROCEDURE DIVISION. 000-SET-SWITCH.

SET MY-SWITCH TO ON. IF SWITCH-ON

THEN DISPLAY "Switch 10 is on". . . .

To change the status of internal switches during execution, turn them on or off from within your program. However, be aware that this information is not saved between runs of the program.

Refer to the Compaq COBOL Reference Manual for more information about setting internal switches.

1.5.2 Setting and Controlling Switches Externally

On Tru64 UNIX systems, to set switches from outside the image, use the SETENV command to change the status of program switches, as follows:

% setenv COBOL_SWITCHES "switch-list"

To remove switch settings:

% unsetenv COBOL_SWITCHES

To check switch settings, enter this command:

% printenv COBOL_SWITCHES Shows switch settings.

The switch-list can contain up to 16 switches separated by commas. To set a switch on, specify it in the switch-list. A switch is off (the default) if you do not specify it in the switch-list.

For example:

% setenv COBOL_SWITCHES "1,5,13" Sets switches 1, 5, and 13 ON. % setenv COBOL_SWITCHES "9,11,16" Sets switches 9, 11, and 16 ON. % setenv COBOL_SWITCHES " " Sets all switches OFF.

♦

On OpenVMS Alpha systems, to set switches from outside the image or for a process, use the DCL DEFINE or ASSIGN command to change the status of program switches as follows:

$ DEFINE COB$SWITCHES "switch-list"

1–60 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.5 Using Program Switches

The switch-list can contain up to 16 switches separated by commas. To set a switch ON, specify it in the switch-list. A switch is OFF (the default) if you do not specify it in the switch-list.

For example:

$ DEFINE COB$SWITCHES "1,5,13" Sets switches 1, 5, and 13 ON. $ DEFINE COB$SWITCHES "9,11,16" Sets switches 9, 11, and 16 ON. $ DEFINE COB$SWITCHES " " Sets all switches OFF.

The order of evaluation for logical name assignments is image, process, group, system. System and group assignments (including Compaq COBOL program switch settings) continue until they are changed or deassigned. Process assignments continue until they are changed, deassigned, or until the process ends. Image assignments end when they are changed or when the image ends.

You should know the system and group assignments for COB$SWITCHES unless you have deﬁned them for your process or image. To check switch settings, enter this command:

$ SHOW LOGICAL COB$SWITCHES

Use the DCL DEASSIGN command to remove the switch-setting logical name from your process and reactivate the group or system logical name (if any):

$ DEASSIGN COB$SWITCHES

To change the status of external switches during execution, follow these steps:

1. Interrupt the image with a STOP (literal-string) COBOL statement. (See the Compaq COBOL Reference Manual for more information.)

2. Use the DCL DEFINE command to change switch settings.

3. Continue execution with the DCL CONTINUE command. Be sure not to force the interrupted image to exit by entering a command that executes another image.

For information about these DCL commands, see the OpenVMS DCL Dictionary.♦ Following is a simple program that displays a message depending on the state

of the logical name COB$SWITCHES (on OpenVMS Alpha systems) or the environment variable COBOL_SWITCHES (on Tru64 UNIX systems):

IDENTIFICATION DIVISION. PROGRAM-ID. TSW.

ENVIRONMENT DIVISION. CONFIGURATION SECTION. SPECIAL-NAMES.

SWITCH 12 IS SW12 ON IS SW12-ON OFF IS SW12-OFF.

PROCEDURE DIVISION. 01-S.

DISPLAY "**TEST SWITCHES**". IF SW12-ON

DISPLAY "SWITCH 12 IS ON".

IF SW12-OFF

DISPLAY "SWITCH 12 IS OFF".

DISPLAY "**END**". STOP RUN.

END PROGRAM TSW.

Developing Compaq COBOL Programs 1–61

Developing Compaq COBOL Programs

1.5 Using Program Switches

On OpenVMS, to test the previous program on an OpenVMS Alpha system, compile and link it and then type the following:

$ DEFINE COB$SWITCHES 12 $ RUN TSW

The output is as follows:

**TEST SWITCHES** SWITCH 12 IS ON **END**

To test the previous program on a Tru64 UNIX system, compile and link it and then type the following:

% setenv COBOL_SWITCHES 12 % tsw

The output is as follows:

**TEST SWITCHES** SWITCH 12 IS ON **END**

♦

1.6 Special Information for Year 2000 Programming

Even subsequent to the turn of the millennium, there still exist potential disruptions in previously problem-free software where there are instances of a two-digit year ﬁeld that should be a four-digit ﬁeld. Programmers need to correct all such ﬁelds, as Compaq cannot prevent problems that originate in application code.

Two-digit year formats used in controlling ﬁelds, or as keys in indexed ﬁles, can cause program logic to become ambiguous. It is a fundamental rule to use four-digit years instead of two-digit years in areas where sequential operations are driven from these values or for comparison of these values.

Compaq COBOL provides programmer access to four-digit and two-digit year formats:

4-digit FUNCTION CURRENT-DATE 4-digit FUNCTION DATE-OF-INTEGER 4-digit FUNCTION DATE-TO-YYYYMMDD 4-digit FUNCTION DAY-OF-INTEGER 4-digit FUNCTION DAY-TO-YYYYDDD 4-digit FUNCTION INTEGER-OF-DATE 4-digit FUNCTION INTEGER-OF-DAY 4-digit FUNCTION TEST-DATE-YYYYMMDD 4-digit FUNCTION TEST-DAY-YYYYDDD 4-digit FUNCTION WHEN-COMPILED 4-digit FUNCTION YEAR-TO-YYYY

2-digit ACCEPT FROM DATE 2-digit ACCEPT FROM DAY

1–62 Developing Compaq COBOL Programs

Developing Compaq COBOL Programs

1.6 Special Information for Year 2000 Programming

4-digit ACCEPT FROM DATE YYYYMMDD 4-digit ACCEPT FROM DAY YYYYDDD

Compaq COBOL offers date functions that can be used in program logic that makes decisions about year order. The full four-digit year handled by the six functions listed should be used in internal program logic decisions that are based on years. External displays of year information can continue to use two-digit formats when that is appropriate.

You should check program logic in code that uses ACCEPT, to verify that millennium transition dates are properly handled.

The use of two-digit years in applications does not automatically create a problem, but a problem could exist. Programmers need to inspect each of their applications for two-digit year dependencies and change any such instances to check the full four-digit year value.

Developing Compaq COBOL Programs 1–63

Handling Numeric Data

Numeric data in Compaq COBOL is evaluated with respect to the algebraic value of the operands.

This chapter describes the following topics concerning numeric data handling:

• How the compiler stores numeric data (Section 2.1)

• Specifying alignment (Section 2.2)

• Sign conventions (Section 2.3)

• Invalid values in numeric items (Section 2.4)

• Evaluating numeric items (Section 2.5)

• Using the MOVE statement (Section 2.6)

• Using the arithmetic statements (Section 2.7)

2.1 How the Compiler Stores Numeric Data

Understanding how data is stored will help you in the following situations:

• When you deﬁne data items to participate in group moves or to be the subject of a REDEFINES clause

• When you move a complex record consisting of several levels of subordination, to be sure that the receiving item is large enough to prevent data truncation

• When you need to use data storage concepts to minimize storage space, particularly when the data ﬁle is large

The storage considerations applicable to tables are described in Chapter 4. For each numeric data item, Compaq COBOL stores the numeric value, and a

sign (if an S appears in the PICTURE clause). The USAGE clause of a numeric data item speciﬁes the data’s internal format in

storage. When you do not specify a USAGE clause, the default usage is DISPLAY. For further information about internal representations, see the USAGE clause tables in the Compaq COBOL Reference Manual.

2.2 Specifying Alignment

In Compaq COBOL, all records, and elementary items with level 01 or 77, begin at an address that is a multiple of 8 bytes (a quadword boundary). By default, the Compaq COBOL compiler will locate a subordinate data item at the next unassigned byte location. However, the SYNCHRONIZED clause, the ﬂag (on Tru64 UNIX), the /ALIGNMENT qualiﬁer (on OpenVMS Alpha), and alignment directives can be used to modify this behavior, causing some numeric data items to be aligned on a 2-, 4-, or 8-byte boundary. You can thus tune data alignment for optimum performance, compatibility with Compaq COBOL for

-align

Handling Numeric Data 2–1

Handling Numeric Data

2.2 Specifying Alignment

OpenVMS VAX, or ﬂexibility. (See Chapter 16, Managing Memory and Data Access and Chapter 15, Optimizing Your Compaq COBOL Program in this manual, and the SYNCHRONIZED clause in the Compaq COBOL Reference Manual for a complete discussion of alignment.)

2.3 Sign Conventions

Compaq COBOL numeric items can be signed or unsigned. Note the following sign conventions:

• If you store a signed result in an unsigned item, only the absolute value is stored. Thus, unsigned items only contain the value zero or a positive value.

• The way Compaq COBOL stores signed results in signed data items depends on the usage and the presence or absence of the SIGN clause.

• When an unsigned result is stored in a signed data item, the sign of the stored result is positive.

Do not use unsigned numeric items in arithmetic operations. They usually cause programming errors and are handled less efﬁciently than signed numeric items. The following example shows how unsigned numeric items can cause errors:

DATA DIVISION . . . 01 A PIC 9(5) COMP VALUE 2. 01 B PIC 9(5) COMP VALUE 5.

Then:

SUBTRACT B FROM A. (A = 3) SUBTRACT 1 FROM A. (A = 2)

However:

COMPUTE A = (A - B) - 1 (A = 4)

The absence of signs for the numeric items A and B results in two different answers after parallel arithmetic operations have been done. This occurs because internal temporaries (required by the COMPUTE statement) are signed. Thus, the result of (A–B) within the COMPUTE statement is –3; –3 minus 1 is –4 and the value of A then becomes 4.

2.4 Invalid Values in Numeric Items

All Compaq COBOL arithmetic operations store valid values in their result items. However, it is possible, through group moves or REDEFINES, to store data in numeric items that do not conform to the data deﬁnitions of those items.

The results of arithmetic operations that use invalid data in numeric items are undeﬁned. You can use the system) or the /CHECK=DECIMAL qualiﬁer (on the OpenVMS Alpha operating system) to validate numeric digits when using display numeric items in a numeric context; note that this ﬂag or qualiﬁer causes a program to terminate abnormally if there is invalid data. In the case of data with blanks (typically, records in a ﬁle), you can use the UNIX) or the /CONVERT qualiﬁer (on OpenVMS Alpha) to change all blanks to zeroes before performing the arithmetic operation. If you specify both the

-check

decimal and the

-check decimal

-convert leading_blanks

ﬂag (on the Tru64 UNIX operating

-convert leading_blanks

ﬂags (on Tru64 UNIX), or

ﬂag (on Tru64

2–2 Handling Numeric Data

both the /CHECK=DECIMAL and the /CONVERT qualiﬁers on OpenVMS Alpha, the conversion of blanks will be done prior to the validation of the resulting numeric digits. Note that the use of either or both of these qualiﬁers increases the execution time of the program. See Compaq COBOL online Help (at the OpenVMS Alpha system prompt), or information.

2.5 Evaluating Numeric Items

Compaq COBOL provides several kinds of conditional expressions used for evaluating numeric items. These conditional expressions include the following:

• The numeric relation condition that compares the item’s contents to another numeric value

• The sign condition that examines the item’s sign to see if it is positive or negative

• The class condition that inspects the item’s digit positions for valid numeric characters

• The success/failure condition that checks the return status codes of COBOL and non-COBOL procedures for success or failure conditions

Handling Numeric Data

2.4 Invalid Values in Numeric Items

man cobol

(on Tru64 UNIX) for more

The following sections explain these conditional expressions in detail.

2.5.1 Numeric Relation Test

A numeric relation test compares two numeric quantities and determines if the speciﬁed relation between them is true. For example, the following statement compares item FIELD1 to item FIELD2 and determines if the numeric value of FIELD1 is greater than the numeric value of FIELD2:

IF FIELD1 > FIELD2 ...

If the relation condition is true, the program control takes the true path of the statement.

Table 2–1 describes the relational operators.

Table 2–1 Numeric Relational Operator Descriptions

Operator Description

IS [NOT] GREATER THAN IS [NOT] >

IS [NOT] LESS THAN IS [NOT] <

IS [NOT] EQUAL TO IS [NOT] =

IS GREATER THAN OR EQUAL TO IS >=

IS LESS THAN OR EQUAL TO IS <=

The ﬁrst operand is greater than (or not greater than) the second operand.

The ﬁrst operand is less than (or not less than) the second operand.

The ﬁrst operand is equal to (or not equal to) the second operand.

The ﬁrst operand is greater than or equal to the second operand.

The ﬁrst operand is less than or equal to the second operand.

Comparison of two numeric operands is valid regardless of their USAGE clauses.

Handling Numeric Data 2–3

Handling Numeric Data

2.5 Evaluating Numeric Items

The length of the literal or arithmetic expression operands (in terms of the number of digits represented) is not signiﬁcant. Zero is a unique value, regardless of the sign.

Unsigned numeric operands are assumed to be positive for comparison. The results of relation tests involving invalid (nonnumeric) data in a numeric item are undeﬁned.

2.5.2 Numeric Sign Test

The sign test compares a numeric quantity to zero and determines if it is greater than (positive), less than (negative), or equal to zero. Both the relation test and the sign test can perform this function. For example, consider the following relation test:

IF FIELD1 > 0 ...

Now consider the following sign test:

IF FIELD1 POSITIVE ...

Both of these tests accomplish the same thing and always arrive at the same result. The sign test, however, shortens the statement and makes it more obvious that the sign is being tested.

Table 2–2 shows the sign tests and their equivalent relation tests.

Table 2–2 Sign Tests

Sign Test Equivalent Relation Test

IF FIELD1 POSITIVE ... IF FIELD1 > 0 ... IF FIELD1 NOT POSITIVE ... IF FIELD1 NOT > 0 ... IF FIELD1 NEGATIVE ... IF FIELD1 < 0 ... IF FIELD1 NOT NEGATIVE ... IF FIELD1 NOT < 0 ... IF FIELD1 ZERO ... IF FIELD1 = 0 ... IF FIELD1 NOT ZERO ... IF FIELD1 NOT = 0 ...

Sign tests do not execute faster or slower than relation tests because the compiler substitutes the equivalent relation test for every correctly written sign test.

2.5.3 Numeric Class Tests

The class test inspects an item to determine if it contains numeric or alphabetic data. For example, the following statement determines if FIELD1 contains numeric data:

IF FIELD1 IS NUMERIC ...

If the item is numeric, the test condition is true, and program control takes the true path of the statement.

Both relation and sign tests determine only if an item’s contents are within a certain range. Therefore, certain items in newly prepared data can pass both the relation and sign tests and still contain data preparation errors.

The NUMERIC class test checks alphanumeric or numeric DISPLAY or COMP-3 usage items for valid numeric digits. If the item being tested contains a sign (whether carried as an overpunched character or as a separate character), the test checks it for a valid sign value. If the character position carrying the sign

2–4 Handling Numeric Data

contains an invalid sign value, the NUMERIC class test rejects the item, and program control takes the false path of the IF statement.

The ALPHABETIC class test check is not valid for an operand described as numeric.

2.5.4 Success/Failure Tests

The success/failure condition tests the return status codes of COBOL and nonCOBOL procedures for success or failure conditions. You test status-code-id as follows:

Handling Numeric Data

2.5 Evaluating Numeric Items



status-code-id IS

You can use the SET statement to initialize or alter the status of status-code-id (which must be a word or longword COMP integer represented by PIC 9(1 to 9) COMP or PIC S9(1 to 9) COMP), as follows:

SET status-code-id TO

The SET statement is typically in the called program, but the calling program may also SET the status of status-code-id. The SUCCESS class condition is true if status-code-id has been set to SUCCESS, otherwise it is false. The FAILURE class condition is true if status-code-id has been set to FAILURE, otherwise it is false. The results are unspeciﬁed if status-code is not set.

Example 2–1 shows the signiﬁcant COBOL code relevant to a success/failure test.

Example 2–1 Success/Failure Test

...

PROGRAM-ID. MAIN-PROG.

...

O1 RETURN-STATUS PIC S9(9) COMP.

...

CALL "PROG-1" GIVING RETURN-STATUS. IF RETURN-STATUS IS FAILURE PERFORM FAILURE-ROUTINE.

...

PROGRAM-ID. PROG-1.

... .

WORKING-STORAGE SECTION. 01 RETURN-STATUS PIC S9(9) COMP. PROCEDURE DIVISION GIVING RETURN-STATUS.

...

IF NUM-1 = NUM-2 ELSE

...

EXIT PROGRAM. END PROGRAM PROG-1. END PROGRAM MAIN-PROG.

SET RETURN-STATUS TO SUCCESS SET RETURN-STATUS TO FAILURE.

SUCCESS FAILURE





SUCCESS FAILURE



Handling Numeric Data 2–5

Handling Numeric Data

2.6 Using the MOVE Statement

The MOVE statement moves the contents of one item into another item. The following sample MOVE statement moves the contents of item FIELD1 into item FIELD2:

MOVE FIELD1 TO FIELD2.

This section considers MOVE statements as applied to numeric and numeric edited data items.

2.6.1 Elementary Numeric Moves

If both items of a MOVE statement are elementary items and the receiving item is numeric, it is an elementary numeric move. The sending item can be numeric, alphanumeric, or numeric-edited. The elementary numeric move converts the data format of the sending item to the data format of the receiving item.

An alphanumeric sending item can be either of the following:

• An elementary alphanumeric data item

• Any alphanumeric literal other than the ﬁgurative constants SPACE, QUOTE, LOW-VALUE, or HIGH-VALUE

The elementary numeric move accepts the ﬁgurative constant ZERO and considers it to be equivalent to the numeric literal 0. It treats alphanumeric sending items as unsigned integers of DISPLAY usage.

When the sending item is numeric-edited, de-editing is applied to establish the unedited numeric value, which may be signed; then the unedited numeric value is moved to the receiving ﬁeld.

If necessary, the numeric move operation converts the sending item to the data format of the receiving item and aligns the sending item’s decimal point on that of the receiving item. Then it moves the sending item’s digits to the corresponding receiving item’s digits.

If the sending item has more digit positions than the receiving item, the decimal point alignment operation truncates the value of the sending item, with resulting loss of digits.

The end truncated (high-order or low-order) depends upon the number of sending item digit positions that ﬁnd matches on each side of the receiving item’s decimal point. If the receiving item has fewer digit positions on both sides of the decimal point, the operation truncates both ends of the sending item. Thus, if an item described as PIC 999V999 is moved to an item described as PIC 99V99, it loses one digit from the left end and one from the right end.

In the execution part of the following examples, the caret ( ^ ) indicates the assumed stored decimal point position:

01 AMOUNT1 PIC 99V99 VALUE ZEROS.

. . . MOVE 123.321 TO AMOUNT1.

Before execution: 00^00 After execution: 23^32

2–6 Handling Numeric Data

Compaq AAQ2G1FTK User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

CompaqCOBOL UserManual

Contents

Preface

Developing Compaq COBOL Programs

Handling Numeric Data