https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Return to Teach Yourself COBOL in 24 Hours, COBOL bibliography, COBOL, COBOL DevOps, Awesome COBOL, Awesome IBM Mainframe, IBM Mainframe development, IBM Mainframe bibliography, Fortran

“ (TYCb24H 1998)

Hour 14 Indexed Files

An Indexed file is a file that allows access to data records by way of a Key field. The file is said to be “Indexed” by this Key. Indexed files are sometimes referred to as keyed files. In this hour, you learn the basics of Indexed file handling, such as

• Defining an Indexed file

• Handling Primary and Alternate Keys

• Writing records with an Indexed file

• Using File Status values

• Using Declaratives

A record in an Indexed file contains at least one Key field. This field is the index to the file. There must be at least one Key field that contains a value that is unique. This Key field is the Primary Key. Each record in the file is uniquely identified by this Key, which functions like a serial number. With this Key you can find and access the remainder of the record. The Key field may be anything from a name to a part number.

An Indexed file is similar to the index of a book. You can go to the index of the book, find a subject, and then go directly to the page on which that subject is discussed. An Indexed file allows you to go directly to a record based upon its Key.

COBOL is one of the few programming languages that incorporates Indexed file methods. Indexed files are very useful. Accessing Indexed files in COBOL is extremely simple and straightforward.

Different COBOL compilers provide different physical Indexed file structures, with varying efficiency. However, the definition and statements used to access an Indexed file are always the same.

Indexed files have many uses. You can use an Indexed file to validate user input. For example, you might store the account numbers of the different dealers in your store in an Indexed file. When an item is sold, you can ask the user for a dealer number. If the number is not in the file, you can issue an error message. This approach is much better than coding each dealer number in the program, where it has to be changed every time you gain or lose a dealer. Validating against a Sequential file is inefficient. With a Sequential dealer file, you might have to Read all the records in the file to validate the dealer number. With an Indexed file, you can determine whether the record is in the file with a single Read.

In addition to keeping the dealer number in the file, you can keep all of the information associated with a dealer in the data record. Doing so allows you to store only the dealer number in the sale transaction data and does not require you to enter or store all the dealer information in each sale record.

Indexed files are ideal for storing any information that you can identify by some Key field. The example in Hour 12 used a table of states. Using a table for this information is very efficient. However, if the number of states or their names chaage frequently, an Indexed file is a better idea. Always analyze your needs to determine which method gives the best performance and is easiest to maintain.

Indexed files need not be limited to a single Key field. For example, you might not know a dealer’s number. If you want to find the dealer number in the file, you might have to Read the entire file, looking for that dealer’s name. Indexed files may have Alternate Key fields. Unlike the Primary Key field, Alternate Key fields may or may not be unique. When you define the Key structure of the file in your COBOL program, you must specify whether any Alternate Key fields may contain duplicates.

Defining the Indexed File Care should be taken in how you design your Indexed file and its Key structure. Changing the Key structure of an established Indexed file can be quite an undertaking. Your main (Primary) Key field must be unique. You should choose something that you know is not likely to change frequently and that identifies the data record. The Key field is either a single elementary item in your record description or a single group field. Most programmers put this Key field at the front of the file, which can facilitate debugging. In addition, some earlier compilers required this placement in support of the computer’s native Indexed file structure. As an example, in this hour you create a dealer master file. The Key is the dealer number, and an Alternate Key is the dealer name. Both Keys are unique. Therefore, you can’t have two dealers with the same name, nor can two dealers share the same dealer number.

You need to decide which information to track for each dealer. The fields used in the example in Hour 4, “Basic User Interface,” are good items to track. These are

• Dealer number

• Name: last, first, and middle

• Address lines 1 and 2

• City, state, and postal code

• Home telephone

• Work telephone

• Other phone

• Start date (when someone became a dealer in your store)

• Last rent paid date

• Next rent due date

• Rent amount

• Consignment percent

The Select Statement for Indexed Files The Select statement is where you define the Key data for the Indexed file. Several items coded on the Select relate to Indexed files.

• Organization Indexed—Specifies that this file is an Indexed file.

• Access Dynamic, Random, or Sequential—Specifies how the records in the file are to be retrieved and/or updated.

• Record Key—Specifies the field that is to be the Primary Key for the file. Only one Primary Key is allowed.

• Alternate Record Key—Specifies a field that is to act as an Alternate Key field for the file. A single file may have multiple Alternate Key statements.

• With Duplicates—If coded, the associated Alternate Record Key may contain duplicates; it does not have to uniquely identify the record as does the Primary Key field.

For an Indexed file, Organization Indexed must be included in the Select statement. One of the three access methods must be chosen. Sequential access causes the Indexed file to behave as a Sequential file. However, instead of reading records in their physical sequence in the file, they are returned in Primary Key sequence. Random access means that every record is retrieved by specifying a Key field. The records may be retrieved in any order. Dynamic access allows you to have the best of both Sequential and Random access. Data records may be accessed randomly via a Key, or you may position the data file at a particular record and then access the file sequentially. You may choose a starting position based on the Primary Key or Alternate Record Key, depending on which you have specified when positioning the file.

In this example, the dealer Indexed file uses Sequential access. The Select statement is coded as follows:

000058 Select Dealer-File Assign to “Dealer.Dat” 000059 Organization Indexed 000060 Access Sequential 000061 Record Key Dealer-Number of Dealer-Record 000062 Alternate Record Key Dealer-Name of Dealer-Record 000063 File Status Dealer-Status. Image

Be careful assigning the physical filename for the file. Some compilers store Indexed files in two components. The index portion might be stored separately from the data portion of the file. Compilers that use this method use a special file extension for the index portion of the file, for example .IDX. Therefore, you should be careful to check your documentation so that you do not assign a name with this extension to your file. The Fujitsu compiler stores the index and data in a single file.

Take note of the qualification of the Key fields. This example uses an Input file that has the same field names, making this qualification necessary.

The FD for your file follows.

000066 File Section. 000067 FD Dealer-File. 000068 01 Dealer-Record. 000069 03 Dealer-Number Pic X(8). 000070 03 Dealer-Name. 000071 05 Last-Name Pic X(25). 000072 05 First-Name Pic X(15). 000073 05 Middle-Name Pic X(10). 000074 03 Address-Line-1 Pic X(50). 000075 03 Address-Line-2 Pic X(50). 000076 03 City Pic X(40). 000077 03 State-or-Country Pic X(20). 000078 03 Postal-Code Pic X(15). 000079 03 Home-Phone Pic X(20). 000080 03 Work-Phone Pic X(20). 000081 03 Other-Phone Pic X(20). 000082 03 Start-Date Pic 9(8). 000083 03 Last-Rent-Paid-Date Pic 9(8). 000084 03 Next-Rent-Due-Date Pic 9(8). 000085 03 Rent-Amount Pic 9(4)V99. 000086 03 Consignment-Percent Pic 9(3). 000087 03 Filler Pic X(50). Notice that the last item in the record description is a 50-character Filler area. This area is provided for future growth in the file. Some time in the future, you might need to add or expand other fields in the file. Leaving a Filler area for expansion makes it easier to modify the layout of the file.

Creating an Indexed File from a Sequential File To explore the different methods for working with Indexed files, you need to create one. The CD-ROM contains a data file named DEALER.TXT. It is located in the \Datafile directory. This file has several records that you can use to create a dealer file.

Listing 14.1 has two files assigned: the Input text file and the Output Indexed file. The start of the program, Select, and FD statements are coded as follows:

Listing 14.1 Dealer File Creation

000001 @OPTIONS MAIN,TEST 000002 Identification Division. 000003 Program-Id. Chapt14a. 000004* Dealer File Creation 000005 Environment Division. 000006 Configuration Section. 000007 Source-Computer. IBM-PC. 000008 Object-Computer. IBM-PC. 000009 Input-Output Section. 000010 File-Control. 000011 Select Dealer-File Assign To “Dealer.Dat” 000012 Organization Indexed 000013 Access Sequential 000014 Record Key Dealer-Number Of Dealer-Record 000015 Alternate Record Key Dealer-Name Of Dealer-Record 000016 File Status Dealer-Status. 000017 Select Dealer-Text Assign To “Dealer.TXT” 000018 Organization Is Line Sequential 000019 File Status Dealer-Text-Status. 000020 000021 Data Division. 000022 File Section. 000023 Fd Dealer-File. 000024 01 Dealer-Record. 000025 03 Dealer-Number Pic X(8). 000026 03 Dealer-Name. 000027 05 Last-Name Pic X(25). 000028 05 First-Name Pic X(15). 000029 05 Middle-Name Pic X(10). 000030 03 Address-Line-1 Pic X(50). 000031 03 Address-Line-2 Pic X(50). 000032 03 City Pic X(40). 000033 03 State-Or-Country Pic X(20). 000034 03 Postal-Code Pic X(15). 000035 03 Home-Phone Pic X(20). 000036 03 Work-Phone Pic X(20). 000037 03 Other-Phone Pic X(20). 000038 03 Start-Date Pic 9(8). 000039 03 Last-Rent-Paid-Date Pic 9(8). 000040 03 Next-Rent-Due-Date Pic 9(8). 000041 03 Rent-Amount Pic 9(4)v99. 000042 03 Consignment-Percent Pic 9(3). 000043 03 Filler Pic X(50). 000044 Fd Dealer-Text. 000045 01 Text-Record. 000046 03 Dealer-Number Pic X(8). 000047 03 Dealer-Name. 000048 05 Last-Name Pic X(25). 000049 05 First-Name Pic X(15). 000050 05 Middle-Name Pic X(10). 000051 03 Address-Line-1 Pic X(50). 000052 03 Address-Line-2 Pic X(50). 000053 03 City Pic X(40). 000054 03 State-Or-Country Pic X(20). 000055 03 Postal-Code Pic X(15). 000056 03 Home-Phone Pic X(20). 000057 03 Work-Phone Pic X(20). 000058 03 Other-Phone Pic X(20). 000059 03 Start-Date Pic 9(8). 000060 03 Last-Rent-Paid-Date Pic 9(8). 000061 03 Next-Rent-Due-Date Pic 9(8). 000062 03 Rent-Amount Pic 9(4)v99. 000063 03 Consignment-Percent Pic 9(3). 000064 03 Filler Pic X(50). 000065 000066 Working-Storage Section. 000067 01 Dealer-Status Pic XX Value Spaces. 000068 01 Dealer-Text-Status Pic XX Value Spaces. 000069 01 Record-Counter Pic 9(5) Value Zeros. To create the file you need to Open the Indexed file, you Open it Output for creation.

Image

Creating an Indexed file by opening it output and accessing it sequentially is normally the most efficient file creation method. In this case, the records being added must already be in Primary Key sequence. Doing so reduces the computer’s overhead as it creates the index entries for the file. You have to remember, however, that the data records for the file must be written in Primary Key sequence. If a record is written out of sequence, an error 21 is reported. The sample data file provided contains records that are in Primary Key sequence.

000070 Procedure Division. 000071 Chapt14a-Start. 000072 Open Input Dealer-Text 000073 Open Output Dealer-File The next step is to Read the Sequential file, creating Indexed file records as you go.

000074 Perform Until Dealer-Status Not = “00” Or 000075 Dealer-Text-Status Not = “00” 000076 Read Dealer-Text 000077 If Dealer-Text-Status = “00” 000078 Write Dealer-Record From Text-Record 000079 If Dealer-Status Not = “00” 000080 Display 000081 “Write Error Dealer-Record ” Dealer-Status 000082 Else 000083 Add 1 To Record-Counter 000084 End-If 000085 End-If 000086 End-Perform 000087 Close Dealer-Text Dealer-File 000088 Display 000089 “File Processed with ” Record-Counter “ Records Written” 000090 Stop Run 000091 . Note the check of the File Status on the Write. Table 14.1 describes the File Status values that might be returned from a Write to an Indexed file opened for Output in Sequential access mode.

In addition to the File Status check, the code adds 1 to the record counter for every successful Write. At the end of the program, this value is displayed.

Image

It is always a good idea, especially when there is no special user interaction, to show the user that the program completed successfully. It is also useful to provide some accounting information such as the number of records processed. If a problem develops, a low or high record count could help diagnose the situation.

Table 14.1 Indexed File Status Values for Writes on Open for Output with Sequential Access

Image

Running this program creates an Indexed file from the Sequential Input file. Notice the Perform loop and how the program terminates when there are no more Input records (as indicated by a non-zero status value on the Input text file) or an error occurs writing to the Output file. Any errors writing to the Output file are reported.

When the program is complete, the output should look like that shown in Figure 14.1.

Figure 14.1 Results of running Chapt14a.

Image

Creating Indexed File Records from User Input Another common way to create an Indexed file is to have the user key the information for the data records into a program. Again, you want to create a new file, so you must Open the file Output. The program to accept user input and to Write to the Indexed file from that input might be coded as shown in Listing 14.2.

Listing 14.2 Dealer Data Entry

000001 @OPTIONS MAIN,TEST 000002 Identification Division. 000003 Program-Id. Chapt14b. 000004* Dealer Data Entry 000005 Environment Division. 000006 Configuration Section. 000007 Special-Names. 000008 Crt Status Is Keyboard-Status 000009 Cursor Is Cursor-Position. 000010 Source-Computer. IBM-PC. 000011 Object-Computer. IBM-PC. 000012 Input-Output Section. 000013 File-Control. 000014 Select Dealer-File Assign To “Dealer.Dat” 000015 Organization Indexed 000016 Access Sequential 000017 Record Key Dealer-Number Of Dealer-Record 000018 Alternate Record Key Dealer-Name Of Dealer-Record 000019 File Status Dealer-Status. 000020 Data Division. 000021 File Section. 000022 Fd Dealer-File. 000023 01 Dealer-Record. 000024 03 Dealer-Number Pic X(8). 000025 03 Dealer-Name. 000026 05 Last-Name Pic X(25). 000027 05 First-Name Pic X(15). 000028 05 Middle-Name Pic X(10). 000029 03 Address-Line-1 Pic X(50). 000030 03 Address-Line-2 Pic X(50). 000031 03 City Pic X(40). 000032 03 State-Or-Country Pic X(20). 000033 03 Postal-Code Pic X(15). 000034 03 Home-Phone Pic X(20). 000035 03 Work-Phone Pic X(20). 000036 03 Other-Phone Pic X(20). 000037 03 Start-Date Pic 9(8). 000038 03 Last-Rent-Paid-Date Pic 9(8). 000039 03 Next-Rent-Due-Date Pic 9(8). 000040 03 Rent-Amount Pic 9(4)v99. 000041 03 Consignment-Percent Pic 9(3). 000042 03 Filler Pic X(50). 000043 Working-Storage Section. 000044 01 Keyboard-Status. 000045 03 Accept-Status Pic 9. 000046 03 Function-Key Pic X. 000047 88 F1-Pressed Value X”01”. 000048 88 F2-Pressed Value X”02”. 000049 03 System-Use Pic X. 000050 01 Cursor-Position. 000051 03 Cursor-Row Pic 9(2) Value 1. 000052 03 Cursor-Column Pic 9(2) Value 1. 000053 01 Dealer-Status Pic X(2) Value Spaces. 000054 88 Dealer-Success Value “00”. 000055 01 Error-Message Pic X(60) Value Spaces. 000056 01 Open-Error. 000057 03 Filler Pic X(26) 000058 Value “Error Opening Dealer File ”. 000059 03 Open-Error-Status Pic X(2). 000060 01 Write-Error. 000061 03 Filler Pic X(26) 000062 Value “Error Writing Dealer File ”. 000063 03 Write-Error-Status Pic X(2). 000064 01 Work-Record. 000065 03 Dealer-Number Pic X(8). 000066 03 Dealer-Name. 000067 05 Last-Name Pic X(25). 000068 05 First-Name Pic X(15). 000069 05 Middle-Name Pic X(10). 000070 03 Address-Line-1 Pic X(50). 000071 03 Address-Line-2 Pic X(50). 000072 03 City Pic X(40). 000073 03 State-Or-Country Pic X(20). 000074 03 Postal-Code Pic X(15). 000075 03 Home-Phone Pic X(20). 000076 03 Work-Phone Pic X(20). 000077 03 Other-Phone Pic X(20). 000078 03 Start-Date Pic 9(8). 000079 03 Last-Rent-Paid-Date Pic 9(8). 000080 03 Next-Rent-Due-Date Pic 9(8). 000081 03 Rent-Amount Pic 9(4)v99. 000082 03 Consignment-Percent Pic 9(3). 000083 000084 Screen Section. 000085 01 Data-Entry-Screen 000086 Blank Screen, Auto 000087 Foreground-Color Is 7, 000088 Background-Color Is 1. 000089* 000090 03 Screen-Literal-Group. 000091 05 Line 01 Column 30 Value “Darlene’s Treasures” 000092 Highlight Foreground-Color 4 Background-Color 1. 000093 05 Line 03 Column 30 Value “Tenant Entry Program” 000094 Highlight. 000095 05 Line 4 Column 01 Value “Number: ”. 000096 05 Line 5 Column 01 Value “Name, Last: ”. 000097 05 Line 5 Column 39 Value “First: ”. 000098 05 Line 5 Column 62 Value “Middle: ”. 000099 05 Line 6 Column 01 Value “Address 1: ”. 000100 05 Line 7 Column 01 Value “Address 2: ”. 000101 05 Line 8 Column 01 Value “City: ”. 000102 05 Line 9 Column 01 Value “Country/State: ”. 000103 05 Line 9 Column 36 Value “Postal Code: ”. 000104 05 Line 11 Column 01 Value “Phone/Home: ”. 000105 05 Line 11 Column 34 Value “Work: ”. 000106 05 Line 12 Column 06 Value “Other: ”. 000107 05 Line 14 Column 01 Value “Start Date: ”. 000108 05 Line 14 Column 24 Value “Last Paid Date: ”. 000109 05 Line 14 Column 51 Value “Next Rent Due on: ”. 000110 05 Line 15 Column 01 Value “Rent Amount: ”. 000111 05 Line 16 Column 01 Value “Consignment Percent: ”. 000112 05 Line 22 Column 01 Value “F1-Exit F2-Save”. 000113* 000114 03 Required-Reverse-Group Reverse-Video Required. 000115 05 Line 4 Column 13 Pic X(8) Using Dealer-Number 000116 Of Work-Record. 000117 05 Line 5 Column 13 Pic X(25) Using Last-Name 000118 Of Work-Record. 000119 05 Line 5 Column 46 Pic X(15) Using First-Name 000120 Of Work-Record. 000121* 000122 03 Reverse-Video-Group Reverse-Video. 000123 05 Line 5 Column 70 Pic X(10) Using Middle-Name 000124 Of Work-Record. 000125 05 Line 6 Column 15 Pic X(50) Using Address-Line-1 000126 Of Work-Record. 000127 05 Line 7 Column 15 Pic X(50) Using Address-Line-2 000128 Of Work-Record. 000129 05 Line 8 Column 15 Pic X(40) Using City 000130 Of Work-Record. 000131 05 Line 9 Column 15 Pic X(20) Using State-Or-Country 000132 Of Work-Record. 000133 05 Line 9 Column 50 Pic X(15) Using Postal-Code 000134 Of Work-Record. 000135 05 Line 11 Column 13 Pic X(20) Using Home-Phone 000136 Of Work-Record. 000137 05 Line 11 Column 41 Pic X(20) Using Work-Phone 000138 Of Work-Record. 000139 05 Line 12 Column 13 Pic X(20) Using Other-Phone 000140 Of Work-Record. 000141 05 Line 14 Column 13 Pic 99/99/9999 Using Start-Date 000142 Of Work-Record. 000143 05 Line 14 Column 40 Pic 99/99/9999 000144 Using Last-Rent-Paid-Date Of Work-Record. 000145 05 Line 14 Column 69 Pic 99/99/9999 000146 Using Next-Rent-Due-Date Of Work-Record. 000147 05 Line 15 Column 14 Pic Z,ZZZ.99 Using Rent-Amount 000148 Of Work-Record. 000149 05 Line 16 Column 22 Pic ZZ9 Using Consignment-Percent 000150 Of Work-Record. 000151 03 Blink-Group Highlight Blink. 000152 05 Line 20 Column 01 Pic X(60) From Error-Message. 000153* 000154 000155 Procedure Division. 000156 Chapt14b-Start. 000157 Perform Open-File 000158 If Dealer-Success 000159 Initialize Work-Record 000160 Perform Process-Screen Until F1-Pressed Or 000161 Not Dealer-Success 000162 Perform Close-File 000163 End-If 000164 Stop Run 000165 . 000166 Process-Screen. 000167 Display Data-Entry-Screen 000168 Accept Data-Entry-Screen 000169 If F2-Pressed 000170 Perform Save-Record 000171 End-If 000172 . 000173 Save-Record. 000174 Move Corresponding Work-Record To Dealer-Record 000175 Write Dealer-Record 000176 If Not Dealer-Success 000177 Move Dealer-Status To Write-Error-Status 000178 Move Write-Error To Error-Message 000179 Perform Display-And-Accept-Error 000180 Else 000181 Initialize Work-Record 000182 Move 1 To Cursor-Row 000183 Cursor-Column 000184 End-If 000185 . 000186 Open-File. 000187 Open Output Dealer-File 000188 If Not Dealer-Success 000189 Move Dealer-Status To Open-Error-Status 000190 Move Open-Error To Error-Message 000191 Perform Display-And-Accept-Error 000192 End-If 000193 . 000194 Close-File. 000195 Close Dealer-File 000196 . 000197 Display-And-Accept-Error. 000198 Display Data-Entry-Screen 000199 Accept Data-Entry-Screen 000200 . When you examine this program, notice that it uses the same data names in the record in Working-Storage and in the data record. Using the same data names allows you to use Move Corresponding later in the program to fill in the record’s data fields from the screen input. Because the same data names were used, they must be qualified in the Using clause by specifying the group of which the data item is a member.

In the program, the data file is Open Output, effectively creating a new file every time the program runs. Sequential access was chosen for performance reasons. However, try running the program and note what happens when you enter a record out of sequence. If you do, a File Status value of 21 is returned. The record was not written in proper Key sequence.

Image

Indexed files may be opened Extend instead of Output and still use Sequential access. If this option is coded, records added to the file must still be in Primary Key sequence, and their Primary Key values must be greater than the last record in the file.

One way to avoid this problem is to Open the file with Random access instead of Sequential access. When Random access is used, records are added based on their Key value. They do not have to be added in sequence. COBOL and the Indexed file system work together to ensure that the records are properly added to the file. File Status 21 errors should no longer occur.

A new File Status value—22—is possible when an Indexed file is Open for Output with Random access. This File Status is returned when a record with a duplicate Key is added to the file. The Key causing the error can be either the Primary Key or the Alternate Key. This error is caused by duplicate Alternate Key values only when duplicates are not allowed on Alternate Keys. If duplicates are allowed on Alternate Keys and a duplicate record is written, the returned File Status is 02. When you code your programs, you need to allow for this status as a valid and successful status.

Change the program to use Random access, instead of Sequential, and recompile the program. The only thing you need to change is the Select statement.

000014 Select Dealer-File Assign to “Dealer.Dat” 000015 Organization Indexed 000016 Access Random 000017 Record Key Dealer-Number Of Dealer-Record 000018 Alternate Record Key Dealer-Name of Dealer-Record 000019 File Status Dealer-Status. Now when you run the program, the order in which the records are added does not matter. Random access allows you to Write records in any position in the file.

Other Methods of Handling File Errors Thus far, you have relied on the File Status values to indicate the success or failure of the Indexed file operations. In addition, two other methods for capturing error conditions are available when using Indexed files.

On the Write statement, you may code an Invalid Key clause. Any statements coded after this clause are executed when an Invalid Key condition occurs. These File Status values begin with a 2. When an Invalid Key condition is encountered, the associated operation is not successful. In this example, you can replace the code in lines 175 through 184 of Listing 14.2 with the following:

000175 Write Dealer-Record 000176 Invalid Key 000177 Move Dealer-Status To Write-Error-Status 000178 Move Write-Error To Error-Message 000179 Perform Display-And-Accept-Error 000180 Not Invalid Key 000181 Initialize Work-Record 000182 Move 1 To Cursor-Row 000183 Cursor-Column 000184 End-Write Notice the use of Invalid Key and Not Invalid Key. When you use Invalid Key, I suggest that you code the End-Write explicit scope terminator. You should remember that the Invalid Key condition is triggered only when a File Status value begins with a 2. I still suggest full and complete File Status value checking as the best way to capture all possible errors, including those for which the File Status value does not begin with a 2.

Image

Another way to handle file errors is to use Declaratives. The use of Declaratives is specified in your program immediately after the Procedure Division by coding the word Declaratives. After the word Declaratives, a Section is coded for each file that is to have declarative logic executed when an error condition occurs. These must be Sections, not Paragraphs. Immediately after the Section header is a Use statement. It tells the program to execute the Declaratives in this section when a file error is detected for the specified file. A file error is defined as any returned File Status value in which the first character is not a zero.

You may separate the Sections within the Declaratives into Paragraphs. You need to remember a few simple rules. You may not Perform any code outside the Declaratives and End-Declaratives labels. However, you may Perform code from different Sections within the Declaratives. For example, you might have a common error-display paragraph that is coded in the Declaratives Section for one file and then performed in the Declaratives Sections for the other files. The Declaratives are not executed for Invalid Key conditions (that is, File Status values starting with 2) if the Invalid Key clause is coded for the file operation. Additionally, File Status 10 (end of file) does not trigger the Declaratives if the At End clause is coded on the Read statement.

The following code shows the Procedure Division from the previous example coded to use Declaratives.

000155 Procedure Division. 000156 Declaratives. 000157 Input-File-Error Section. 000158 Use After Standard Error Procedure On Dealer-File. 000159 Dealer-File-Error. 000160 String “Error On Dealer-File ” Dealer-Status 000161 Delimited By Size Into Error-Message 000162 End-String 000163 Display Data-Entry-Screen 000164 Accept Data-Entry-Screen 000165 . 000166 End Declaratives. 000167 Chapt14d-Start Section. 000168 Perform Open-File 000169 If Dealer-Success 000170 Initialize Work-Record 000171 Perform Process-Screen Until F1-Pressed Or 000172 Not Dealer-Success 000173 Perform Close-File 000174 End-If 000175 Stop Run 000176 . 000177 Process-Screen. 000178 Perform Display-And-Accept 000179 If F2-Pressed 000180 Perform Save-Record 000181 End-if 000182 . 000183 Save-Record. 000184 Move Corresponding Work-Record to Dealer-Record 000185 Write Dealer-Record 000186 Invalid Key 000187 Move Dealer-Status to Write-Error-Status 000188 Move Write-Error to Error-Message 000189 Perform Display-And-Accept 000190 Not Invalid Key 000191 Initialize Work-Record 000192 Move 1 to Cursor-Row 000193 Cursor-Column 000194 End-Write 000195 . 000196 Display-And-Accept. 000197 Display Data-Entry-Screen 000198 Accept Data-Entry-Screen 000199 . 000200 Open-File. 000201 Open Output Dealer-File 000202 . 000203 Close-File. 000204 Close Dealer-File 000205 . In the program, the screen Accept and Display were changed to use a common routine: Display-And-Accept. However, it is not Performed from the Declaratives Section of the program. You cannot Perform anything outside the Declaratives from within the Declaratives.

Notice the use of the Invalid Key clause with the Write statement. Because Invalid Key is coded the Declaratives will be executed on any file error encountered other than an Invalid Key condition. Coding for the Invalid Key in addition to using Declaratives allows you to capture any and all file errors that might occur.

Summary In this hour, you learned the following:

• Indexed files are those files whose records are keyed by specified Key fields.

• The Primary Key field of an Indexed file must be unique.

• One or more Alternate Key fields may be specified. They are not required. When specified, they may be defined as allowing duplicate records.

• When an Indexed file is opened for Output and the access mode specified is Sequential, any records written to the file must be written in Primary key sequence order.

• When an Indexed file is opened for Output and the access mode specified is Random, the records may be written in any order.

• File Status values may be checked to determine the result of Indexed file operations, such as Open, Close, and Write.

• In addition to File Status values, the Invalid Key clause can be coded to test for the Invalid Key condition.

• Declaratives allow you to code a common error-handling routine for any invalid File Status values returned for operations against the specified files.

Q&A Q When using an Indexed file opened for Output with Sequential access, if I have to be so careful about adding records in the proper sequence, why would I ever want to use Sequential access?

A When processing large amounts of data, you will find that adding records in random order is much slower than adding them in Sequential order. For each Add in random order, the program must check whether the record already exists, add the record in the proper portion of the data file, and then adjust the index records accordingly. With Sequential access, the program need only verify that the Key value currently being written is greater than the last Key value written. All the records are in sequence and can be added efficiently. Key maintenance is simplified for the program as well.

Q When I run the example program, I get a File Status 22. What does that mean?

A Either the Primary Key value of the record you are adding is duplicated, or the Alternate Key is not specified to allow duplicates, and you have duplicated that Key value.

Q I understand the various File Status values, but what does Invalid Key mean?

A The Invalid Key clause is an easy way to catch a range of errors in Indexed file operations. These errors relate to problems associated with the Key values. File Status values that are associated with the Invalid Key condition begin with a 2.

Q I can see some good uses for Declaratives. But if they are a catch-all, how can I tell exactly what was happening when the error occurred?

A You are right. Using Declaratives can save a lot of coding. However, because they will be executed for any error not explicitly coded for with an At End or Invalid Key clause, they are not very specific. You can compensate by setting up a common area where you store information like the filename and the type of operation being attempted, for example, Open, Write, Close. You can use this area to be specific when reporting errors that occur.

Workshop To help reinforce your understanding of the material presented in this hour, refer to the section “Quiz and Exercise Questions and Answers” that can be found on the CD. This section contains quiz questions and exercises for you to complete, as well as the corresponding answers.

Fair Use Sources:

• B001FWIJGE (TYCb24H 1998)