Chapter 17

Display Files

In the last three chapters, you learned about the organization of internal files and how to process them with three methods of access: sequential, relative, and keyed. This chapter introduces a second type of file, called display files.

Display files are used in Business Rules! in several important places. A program saved as source code is a display file. Procedures (which will be covered in the next chapter) are also display files. When you use the PRINT statement to send a stream of characters to the screen or printer, you are using display files.

OPEN, CLOSE and RESTORE statements have similar -- but not always identical - capabilities with both display and internal files. The other I/O statements used with internal files are not used with display files. With display files, input and output are handled with the same statements used on the screen: PRINT, INPUT and LINPUT. The material in this chapter will be new, and yet it also will be old because you have seen all these statements before.

When you finish you will be able to:

• Identify differences between display and internal files.
• Define what a display file is.
• OPEN a new or existing display file.
• Use the PRINT and RESTORE statements with display files open for output.
• Use the INPUT, LINPUT and RESTORE statements with display files open for input.

What is the defining characteristic of display files? The data contained in display files can be printed or displayed. It is often useful to think of display files as printer files. They can be sent to a printer (or the screen) without any changes. There should be no unusual non-printing characters. Each new line on the printout should correspond to an output statement in the program that produced the file.

17.1 What’s the difference between display and internal files?

Display and internal files differ both in their capabilities and in the rules for using them. Later sections in this chapter will focus on the rules for display file processing, and this section will focus on differences in capabilities. Many of these differences will appear to be advantages for internal files.

While using internal files is often preferred or required in most application programs, display files still have many important uses.

Display files cannot be used with the SORT or INDEX command. Only sequential processing is allowed with display files. Individual records in a display file cannot be deleted or updated because display files cannot be opened OUTIN. Please to not interpret this to mean that data in display files can never be erased or changed on your disk; DROP and FREE commands can be used with display files, and then they can be written over with new data.

Quick Quiz 17.1

For each item listed below, indicate where they can be used by choosing display, internal or both.

1. Display Internal Both Can be opened KEYED
2. Display Internal Both Can be opened OUTIN
3. Display Internal Both Can be opened SEQUENTIAL
4. Display Internal Both Can be opened INPUT
5. Display Internal Both Can be used with DELETE statement
6. Display Internal Both Can be used with READ statement
7. Display Internal Both Can be used with RESTORE statement
8. Display Internal Both Can be used with CLOSE statement
9. Display Internal Both Can be used with SORT command
10. Display Internal Both Can be used with PRINT statement

Answers 17.1

17.2 Using the OPEN statement for an existing display file.

In the chapters on internal files, several arbitrary conventions for file extensions were introduced. For display files, the arbitrary choice will be that display files will have the extension .TXT -- unless some other convention is clearer (such as .BRS for a source program).

Output to a display file can be directed to the screen, the printer, or a file (either on hard disk, usb or other location). This selection is made with the file number. In the chapters on internal files, it was stressed that a file must be opened before any input or output could take place. For display files, there are two exceptions to this rule: one for the screen, and one for the printer. Business Rules! includes two pre-defined file numbers:

255 defaults to the printer (with PRINT), and
0 is reserved for the screen (with PRINT) and for the keyboard (with INPUT, LINPUT, and RINPUT).

As you might expect, one major difference in the OPEN statements for the two types of files is that the keyword DISPLAY is used in place of the keyword INTERNAL to specify the type of file.

500 OPEN #15: “NAME=MESSAGE.DIS,RECL=132”, DISPLAY,INPUT

The parts above are: Line number, File number, File ID String, File Type, and Type of Use.

Again, the file number is an arbitrary number from 1 to 127, and also 255. File number 0 can be used for both input and output, but is not legal in an OPEN statement. In a nutshell, the purpose of the OPEN statement is to define the file number as equivalent to a special device (such as screen or printer) or a specific file in a specific directory on a specific drive or location.

The file identification string is the only one place that the name of the file needs to be mentioned in the program. Within the file identification string, there is the second major difference between display and internal files. The RECL= clause is used only for new display and internal files, but can be used with new or old display files. If RECL= is not specified, the default is a record length of 132 for both new and existing files.

The last keyword may be either INPUT or OUTPUT. INPUT should be used when the file will only be read. INPUT implies that no new information will be added to the file. OUTPUT should be used when only adding new records to the file.

OUTPUT implies that no information will be read from the file.

When a DISPLAY file is open for INPUT, the sequential pointer is positioned at the beginning of the file. When a DISPLAY file is open for OUTPUT, the sequential pointer is positioned at the end of the file, so that records will be added at the end of existing records. To override this, a RESTORE statement can be used to move the pointer back to the beginning of the file, so that new records will clobber the old records (similar to executing a DROP command).

Notice that OUTIN is not possible for display files. Also, you no longer have the choice of sequential, relative, or keyed. Display files can only be processed sequentially.

Quick Quiz 17.2

True or False:

1. You must always have an OPEN statement to define the file number before doing any input or output to a display file.

2. Output to a display file can be directed to the screen, the printer, or a file.

3. 255 is a special file number that defaults to the printer.

4. The RECL= clause can be used in the OPEN statement with new or old display files.

5. The keywords EXTERNAL, INTERNAL, OUTIN, RELATIVE, and KEYED can not be used in the OPEN statement for a display file.

Answers 17.2

17.3 Using the OPEN statement to create a new display file.

An OPEN statement must be executed for a particular file before any I/O statement can act on that file.

This section discusses opening internal files, which are one of three major file types in Business Rules! (the other two file types are display and external).

Internal files can be opened for INPUT, OUTPUT, or OUTIN; OUTIN allows both input and output at the same time. Whereas display files are restricted to sequential processing, internal files can be accessed as SEQUENTIAL (in chronological order), RELATIVE (according to record position) or KEYED (according to keyed position). Internal files can be used for sorting and indexing; display and external files cannot.

Internal files utilize six I/O statements: READ, REREAD, WRITE, and REWRITE, DELETE and RESTORE. Unlike display files, internal files support special numeric formats (such as packed decimal) and have a fixed record length. A header record, which is transparent to the user, keeps track of the record length, number of the last record used, etc.

Before reading input from an existing internal file called STATES, a program must have a statement such as the following:

500 OPEN #2: "name=STATES", INTERNAL, INPUT, SEQUENTIAL

After line 500 is executed, the internal file STATES can be used for input using the file number, #2. The following statement would create a new internal file called ZIPCODES and define a record length of 31 bytes:

510 OPEN #3: "NAME=zipcodes, NEW, recl=31", INTERNAL, OUTPUT, RELATIVE

A string constant, string variable, or string expression can be used for the OPEN statement clause which indicates what file is to be opened. Consider the following examples.

1000 OPEN #1: "NAME=CUSTOMER.DAT", INTERNAL, INPUT
1005 PRINT "Enter FILE for balances"
1010 INPUT F$
1015 LET F$ = "NAME=" & F$ & ".DAT"
1020 OPEN #2: F$, INTERNAL, INPUT, SEQUENTIAL
1030 OPEN #3: "NAME=SALES"&STR$(MONTH)&" .DAT", INTERNAL, INPUT, RELATIVE

Line 1000 shows OPEN using a string constant. Lines 1005 to 1020 show opening a file with a name constructed from a prompted keyboard entry. Line 1030 will open the file SALES10.DAT if the value of MONTH is 10.

The KPS= and KLN= parameters (denoted by the "key-spec" parameter in the diagram) can be used to create an index file at the same time that a master file is being created. The following example shows how a single key can be a combination of three sections of the record (up to six sections may be defined). KPS specifies the starting position of each key section and KLN specifies the length of each section (the first section starts in column 1 and is 4 bytes in length; the second starts in column 10 and is 2 bytes in length; the third starts in column 20 and is 2 bytes in length).

100 OPEN #9: "NAME=history, REPLACE, RECL=80, KFNAME=hist.key, KPS=1/10/20,KLN=4/2 /2", INTERNAL, OUTPUT, KEYED

The required "file-num" parameter is a numeric expression that must equal 255 or an integer from 1 to 127, inclusive. Two special default values for "file-num" are provided to facilitate I/O from the keyboard and to the printer and screen. These special defaults are: #0 (reserved for keyboard input and screen output), and #255 (reserved for printer, equivalent to DOS PRN:). No OPEN is necessary for these two reserved values.

From this point, there are two possible paths through the OPEN internal syntax. The top path will be described first.

"NAME = file-ref" is a required parameter which specifies the file or device to be opened. This parameter can be a string constant, string variable, or string expression.

The "NEW" parameter indicates that the file to be opened must also be newly created. Error 4150 (duplicate file name) will occur if NEW is specified and the file already exists.

The "USE" parameter indicates that an existing file by the specified name should be opened. If a file by the specified name does not exist, Business Rules! will create a new file for it.

The "REPLACE" parameter indicates that any existing file under the specified name should be freed and that a new file under that same name be created. There will be no warning that the file is being replaced when this parameter is used.

"RECL = integer" is an optional parameter used to specify the record length. This parameter must be used with new files, but is never used with existing files since the system stores the record length for internal files in the header record.

The "KFNAME = file-ref" parameter specifies the name of an index file. It is required when a file is being opened for KEYED processing.

The "key-spec" parameter represents an insertable syntax that indicates the starting positions and lengths of up to six different key sections in a record. This parameter can be used only when the program is to create a new master file and a new index file. It is not necessary for the key sections to be adjacent to one another, but they may not exceed a combined length of more than 128 bytes. Within the key-spec syntax, the "KPS=" keyword may be followed by up to six "starting pos" specifications, each of which identifies the starting position of a key section; multiple specifications are separated by a forward slash. The "KLN=" keyword must be followed by the "length" parameter, which identifies the lengths of each of the key sections which were specified by the "starting pos" parameter.

Four options are available for the "share spec" parameter: NOSHR, SHR, SHRI and SHRU:

NOSHR indicates that the current workstation is to have exclusive access to the file. No other opens are permitted to the same file until it has been closed.

NOSHR is the default when a "share spec" is not specified.

SHRI allows others to use the file for input only. Others may read but not change a file opened SHRI.

SHR allows others to read, write and update an open file. An individual record within this file may be locked during use when either OUTPUT or OUTIN is also specified and when the I/O statement utilizes the RESERVE parameter (RESERVE is the default, so explicit coding is not necessary).

SHRU operates the same as SHR; it is maintained for System/23 compatibility.

"RESERVE" locks the file until otherwise specified; other users are denied access even when the file is not open. A reserved file is not released until a CLOSE statement with the RELEASE parameter has been specified or until a PROTECT file-ref, RELEASE command has been issued (this last command is ignored by the IBM PC-NetWork operating system). Exiting Business Rules! also releases all files locked by that workstation.

The "WAIT= int" parameter specifies the number of seconds that Business Rules! should wait for a locked record before generating error code 0061. The "TRANSLATE=file-ref" parameter indicates that character translation is required for all input or output of C, V, G, N, ZD or PIC strings. The file-ref must identify either a 256- or 512-byte file. The first 256 bytes are used as an input translation table.

The above parameters (excluding the #filenum parameter) make up the file identification string. They must all be enclosed within a single set of quotation marks. If you wish to define this information elsewhere in the program, Business Rules! will accept the "string- expr" parameter in their place. The following parameter descriptions apply to all forms of the OPEN display statement, no matter which syntax path is selected.

The "INTERNAL" keyword is required; it identifies the file as an internal file.

"INPUT" indicates that information in the file will be input into the program.
"OUTPUT" indicates that information from the program will be output to the file.
OUTIN indicates that information will be both input into the program and output to the file. One of these three keywords is required.

The keywords "SEQUENTIAL", "RELATIVE", and "KEYED" are optional parameters that specify the method of access. The default is SEQUENTIAL access.

Quick Quiz 17.3

True or False:

1. For a display file, the presence of RECL= in the OPEN statement indicates that Business Rules! will try to create a new file.

2. When trying to create a new display file, coding the REPLACE parameter at the end of the file identification string will override a possible error if the file already exists.

3. The PAGEOFLOW= clause is used to help set up top and bottom margins for printed reports.

Answers 17.3

17.4 Using display files for output.

Back in Chapter 6, you learned how to use the PRINT statement with zone printing (items separated by commas), without zone printing (items separated by semi-colons), and under format control with a USING clause and a FORM statement. All of this applies to the PRINT statement when used to add records to a display file.

In that chapter you learned about printing to the screen as well as to the printer. Now that you know about file numbers, perhaps it is easier to see why the #255 was important in the difference between the following two statements:

120 PRINT #255: NAME$, ADDR$
130 PRINT NAME$, ADDR$

255 is simply the file number for a special display file for the printer. It is as if your program included a statement like this before the first PRINT #255:

1 OPEN #255:”NAME=PRN:,RECL=132,PAGEOFLOW=60,DISPLAY,OUTPUT

The default for the PRINT statement is file number 0, which is another special display file for the screen. The following two statements are equivalent.

120 PRINT #0: NAME$, ADDR$
130 PRINT NAME$, ADDR$

The RESTORE statement with display files is exactly like the RESTORE statement was used with internal files with the sequential method of access. RESTORE moves the file-pointer to the beginning of a DISPLAY file. When a file is OPEN for output, the pointer is initially positioned at the end of the file, so that new records will be added to the end of the file. A RESTORE statement can be used to override this. If a RESTORE statement is used, the pointer will be moved to the beginning of the file, but this will also erase the current contents of the file (like a DROP command).

Quick Quiz 17.4

True or False:

1. The WRITE statement is used for output to display files.

2. The RESTORE statement can be used with display files open for output.

3. PRINT #0:”HI” and PRINT “HI” would both produce identical output to the screen.

Answers 17.4

17.5 Using display files for input.

When a display file is opened with the keyword INPUT, the INPUT, LINPUT and RESTORE statements may be used. The RINPUT statement can only be used with file number 0, the screen and keyboard.

RINPUT cannot be used more generally with display files because RINPUT is a combination of PRINT and LINPUT; combinations of output and input to the same file are not allowed (except with RINPUT on the screen).

Back in Chapter 5, you learned how to use the INPUT and LINPUT statements for entering data from the keyboard. All of this applies to these two statements when they are used with display files. The general purpose of the INPUT statement is to assign values to variables from a display file as if the data were being typed in at the keyboard.

The default for the INPUT and LINPUT statement if file number 0, which another special display file for the keyboard. The following two statements are equivalent.

120 INPUT #0: NAME$, ADDR%
130 INPUT NAME$, ADDR$

The general purpose of the LINPUT statement is to assign a value to a single string variable from an entire line (record) of a display file as if the data were being typed in at the keyboard. The input string may contain commas and other punctuation as well as leading trailing blanks will be removed.

What is the difference between INPUT and LINPUT?

INPUT can be used with more than one variable, but LINPUT can only accept a single variable. This one variable must be a string with LINPUT while INPUT cannot include commas (unless the string is surrounded by quotation marks) because a comma is used to separate the items being entered. With LINPUT, the only separation of items is at the end of a record (CR and LF, or just LF). Strings entered with LINPUT may include commas.

The RESTORE statement with display files for input exactly like the RESTORE statement as used with internal files with the sequential method of access. From any position in the file, RESTORE moves the pointer to the beginning of a DISPLAY file. When a file is OPEN for input, there is no possibility for loss of data as there is when using RESTORE with a display file opened for output.

Here is a common problem using INPUT with display files. Consider what happens in the following program when the two numbers in line 250 are written to the file.

200 OPEN #10:”NAME=PROBLEM.DIS”,DISPLAY,OUTPUT
250 PRINT #10: 15, 19
300 CLOSE #10
350 OPEN #20:”NAME=PROBLEM.DIS”,DISPLAY,INPUT
400 INPUT #20: A, B EOF
450 PRINT A, B
500 CLOSE #20
550 STOP
600 PRINT A, B

It would seem that the record written in line 250 could be read back in with the statement in line 400. However, and error 4270 will be generated prematurely at line 400. The program will branch to line 600 and will print 1519 and 0 for the values of the two variables.

The problem can be seen by considering that 400 should be like INPUT from the keyboard. INPUT from the keyboard would require a comma between the two values. Line 350 would output, as if to the screen,

15 19

What is needed to get the required comma in the file output is something like this new line 250:

250 PRINT #10:15, “,”, 19

The output from the new line 250 would generate the following

15 , 19

Although this would execute properly, the extra spaces in the output record could be eliminated by PRINT USING with a FORM statement or using a semi-colon instead of a comma to eliminate zone printing, example:

250 PRINT #10:15;”,”: 19

Quick Quiz 17.5

True or False:

1. The READ statement is used for input with display files.

2. The RESTORE statement can be used with display files open for input without any possibility of the loss of data which occurs when RESTORE is used with display files open for output.

3. INPUT #0: TEMP$ and INPUT TEMP$ are both equivalent ways of accepting data from the keyboard.

4. When your program opens a display file for input, both the LINPUT statement and the RINPUT statement may be used to accept string data.

5. Strings read from a display file using the LINPUT statement may include commas and other punctuation marks as well as leading blanks.

Answers 17.5

NEXT:Error Handling and Recovery

Back to Index