FILE-CONTROL.
SELECT
Each file used in the program must first be defined with a Select sentence in
the File-Control paragraph.
OPTIONAL
An optional file is handled differently when the file is opened.
The following table shows its effect.
OPEN MODE | OPTIONAL | File available | |
---|---|---|---|
Yes | No | ||
INPUT | No | Normal open | Runtime error 35: file not found |
Yes | Normal open | Normal open, Status 35: The first read causes: At end - Status 15, or Invalid key - Status 25: optional file not present |
|
I-O | No | Normal open | Runtime errror 35 |
Yes | Normal open | The OPEN creates the file | |
OUTPUT | - | A new version of the file is always created, replacing any existing version. OPTIONAL has no effect on OUTPUT files. |
EXTEND | No | Normal opeen | Runtime error 35 |
Yes | Normal open | The OPEN creates the file |
RESERVE
This clause has no effect, and is ignored.
FILE STATUS
This clause is used to identify a two-character field in the Working-Storage
Section of the program which is to contain the status resulting from each
statement in the Procedure Division.
This clause is optional, but must be included if a Use statement is included
for this file.
The first character of the status code identifies the class of exception:
0 Successful completion, comment only. 1 End of file condition. 2 Invalid key condition. 3 Permanent error, generally physical I-O errors. 4 Logic error, improper operation sequence or limit violation. 9 General error. The codes which may be returned in this field are as follows. 00 Successful completion 02 Duplicate key created 05 Optional file not present 08 BTRIEVE status 80, 84, or 85 10 Logical end of records 12 End of Page 14 Relative key field overflow 15 Optional file not present 21 Key sequence error 22 Invalid duplicate key 23 Record (key) not found 24 Invalid key modification 25 Optional file not present 30 Undefined permanent errors 33 Record longer than BTRIEVE page 34 Record longer than record area 35 File not found 40 Previous fatal error 41 File already open 42 File not open 43 No current record 44 Length of updated record changed 45 Path (directory) not found 46 Record already exists 47 Wrong open mode or file type 48 Wrong number of keys specified 49 Too many files open 91 Btrieve Lock or Unlock error 92 Btrieve Transaction error 94 Directory full 95 Disk full 96 Indexed file syatem not installed
I-O-CONTROLThis paragraph has no effect and is ignored.
FILE SECTION FDEach file defined with a Select statement must also be specified with an FD statement in the Data Division File Section, followed by the data definition of one or more records for that file.
[ BLOCK CONTAINS [min-block TO] block-size |RECORDS|CHARACTERS| ]This clause has no effect, and is ignored.
[ RECORD CONTAINS rec-size CHARACTERS ]This clause has no effect. The record length is defined by the length of the defined record area.
[ DATA |RECORDS ARE|RECORD IS| {rec-name}... ]This clause has no effect, and is ignored.
PROCEDURE DIVISION. USE |SYSTEM|proc-name [THRU proc-end]| FOR EXCEPTION ON file-nameThis statement may occur more than once anywhere in the Procedure division to define how file exceptions are to be handled. The File Status must be defined in each file which is referenced in a Use statement. The referenced procedure will be called when an status code greater than 29 occurs on the referenced file or files.
The referenced procedure may include file operations, including operations on the file with the exception. If a further exception occurs on this or any other file during this procedure however, the program will be mandatorily terminated.
The logical flow of the program must proceed to the end of the named procedure, or Proc-end, otherwise ®anyŻ subsequent file exception will cause program termination.
At the end of the referenced procedure, the program resumes with the statement immediately following the statement in which the exception was detected.
If SYSTEM is used instead of a procedure name, the exception is handled by the runtime system, which will abnormally terminate the program with an appropriate comment identifying the exception. This is the default condition; this option is normally used therefore, to cancel a previous USE statement.
ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT [OPTIONAL] file-name ASSIGN TO PRINTER [ [ORGANIZATION IS] SEQUENTIAL ] [ACCESS MODE IS SEQUENTIAL] [FILE STATUS IS file-status] .
ASSIGN TO PRINTER
This is a mandatory statement to associate this file with the printer, but not
necessarily to be physically printed by this program.
DATA DIVISION.
FILE SECTION.
FD file-name
[ LINAGE IS page-size LINES
[WITH FOOTING AT footing-line]
[LINES AT TOP top-lines]
[LINES AT BOTTOM bottom-lines]
[LINAGE-COUNTER IS binary-counter] ]
LABEL |RECORDS ARE|RECORD IS|
| STANDARD VALUE OF FILE-ID IS file-path |
| OMITTED | .
Note. The following items are expressed as literal values:
Page-size, Footing-line, Top-lines, Bottom-lines.
LINAGE
The lines on a page which may be printed or spaced to.
FOOTING
The first line within Linage which warns of the end of page. Printing will
only take place in this area without an end of page warning when:
TOP
The lines at the top of the page. No printing occurs here.
BOTTOM
The lines at the bottom of the page. No printing occurs here.
LINAGE-COUNTER
The Linage-counter is a COMP data item defined by the system, containing the
current line number within the page body after each WRITE statement to a print
file. This clause is used to identify a COMP data item which is defined in
the program and is to be used instead. This is only necessary when the
program contains more than one print file because there is only one Linage-
counter defined by the system. LINAGE-COUNTER may be tested by the program
but may not be altered. Binary-counter may be tested in the same way. It may
also be altered but this will have no effect; an internal counter always
controls the printing process and Binary-counter will be reset to the correct
value after each WRITE statement. When the file is first opened, LINAGE-
COUNTER (and any Binary-counter) contains 1.
Logical Page.
The logical page size is defined by Linage plus Top plus Bottom.
Example:
LINAGE IS 60 LINES FOOTING 57 TOP 3 BOTTOM 3
Logical page |
T1 TOP  T2 T3 |
|
---|---|---|
LINAGE Page body |
1 2 3 Detail .. lines 56 |
|
57 58 FOOTING 59 60 |
||
B1 B2 BOTTOM B3 |
LABEL RECORDS
If STANDARD, the data is written to a disk file with the specified name, which
may be a data item containing the name, or a literal file path. However, if
the data item contains "PRN" at run time, the data will be written directly to
the printer.
If OMITTED, The data is written directly to the printer.
PROCEDURE DIVISION.
OPEN { |OUTPUT|EXTEND| {file-name}... }...
Extend affects only a disk file, appending the data to the end of an existing
file.
CLOSE {file-name}...
WRITE rec-name [FROM src-item]
[ |BEFORE|AFTER| ADVANCING |PAGE|count [|lines|line| |
|ON LINE line-number |
|WITH NO ADVANCING | ]
[ AT |END-OF-PAGE|EOP| statements
[ ELSE statements ]
[ END-WRITE ] ]
ADVANCING PAGE
If the LINAGE clause is included the required number of lines to the next page
is calculated, and the paper is moved that number of spaces. Without LINAGE,
this phrase generates a formfeed character to the file or the printer.
ON LINE
This is a non-standard feature. It may only be used if the LINAGE clause is
included. Its effect is to move to a specific line in the page body. Line-
number may be a literal or a numeric item.
WITH NO ADVANCING
This is a non-standard option to allow printer control codes to be written to
the printer from the record without affecting the line spacing in any way. If
data is written with this option, it will be added to the current line.
END-OF-PAGE, EOP
These two words are equivalent. It may only be used if the LINAGE clause is
included. The EOP statements are executed depending on the spacing associated
with the print line, as follows.
ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT [OPTIONAL] file-name ASSIGN TO DISK [ [ORGANIZATION IS] SEQUENTIAL ] [ACCESS MODE IS SEQUENTIAL] [ RECORD DELIMITER IS STANDARD-1 [PADDING CHARACTER IS pad-char] ] [FILE STATUS IS file-status] .
RECORD DELIMITER
This identifies a file in which each record is truncated and ends with the
Carriage-return and Linefeed characters - hexadecimal 0D0A. The truncated
characters are the Padding character, or spaces by default. When records are
written, any trailing padding characters are truncated and hexadecimal 0D0A is
appended to the record. When records are input, The record area is filled to
its full length with the padding character, and the hexadecimal 0D0A is
omitted.
The defined record length is the maximum length of the data in any record,
excluding the appended hexadecimal 0D0A.
DATA DIVISION.
FILE SECTION.
FD file-name
LABEL |RECORDS ARE|RECORD IS|
|STANDARD|header-record|
VALUE OF FILE-ID IS file-path .
LABEL RECORD IS header-record
This is a non-standard option to define a header record at the start of the
file without DELIMITER before the first normal data record. This provides for
the file definition record at the head of most database system files, but it
may also be used for a user-defined summary control information record. The
length of the header record is defined by the definition of "header-record" in
the WORKING-STORAGE SECTION.
When the file is opened in OUTPUT mode, or an OPTIONAL file is not present in I-O or EXTEND mode, The header record present in the defined area is written to the start of the file. When the file is opened in any other circumstance, the existing header record is read into the defined area.
When a file in any mode except INPUT is closed, the header record in the defined area is rewritten to the file. The header record may therefore be updated during the processing of the file. Note that this occurs only with the CLOSE statement, but not if the system is left to close the file at STOP RUN.
PROCEDURE DIVISION.
OPEN {| INPUT | {file-name}... }...
| OUTPUT |
| EXTEND |
| I-O |
CLOSE {file-name}...
READ file-name [[NEXT] RECORD] [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
REWRITE rec-name [FROM src-item]
The previous successful operation on the file must be a Read statement. The
file must be opened in I-O mode. The length of delimited records cannot be
increased.
WRITE rec-name [FROM src-item]
ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT [OPTIONAL] file-name ASSIGN TO DISK [ORGANIZATION IS] RELATIVE | [ACCESS MODE IS SEQUENTIAL][RELATIVE KEY IS rel-key] | | ACCESS MODE IS RANDOM RELATIVE KEY IS rel-key | | ACCESS MODE IS DYNAMIC RELATIVE KEY IS rel-key | [FILE STATUS IS file-status] .
RELATIVE KEY
A numeric data item defined in the program, to contain a record number in the
file. The first record in the file is record 1.
When reading or writing records sequentially and the relative key is
specified, the relative key will be set to the record number of the latest
record processed. When processing records randomly, relative key specifies
the record to be read, written, rewritten or deleted.
DATA DIVISION.
FILE SECTION.
FD file-name
LABEL |RECORDS ARE|RECORD IS| STANDARD
VALUE OF FILE-ID IS file-path .
Relative file records on disk are one character longer than the defined
length. This extra character is not available to the program.
PROCEDURE DIVISION.
OPEN {| INPUT | {file-name}... }...
| OUTPUT |
| EXTEND |
| I-O |
CLOSE {file-name}...
START file-name [ KEY IS | EQUAL TO | rel-key
| = |
| GREATER THAN |
| > |
| NOT LESS THAN |
| NOT < |
INVALID KEY statements
[ELSE statements]
[END-START]
Access Sequential or Dynamic
This statement does not access a record; it
defines a record from which serial access is to commence. A following Read
Next statement will access this record. If the next statement is Read Prior,
the record before the selected record will be accessed. Rel-key is the
defined relative key; its value is not changed by this statement. If the key
phrase is omitted, the default is: KEY IS EQUAL TO rel-key.
KEY
Defines the record from which access is to begin. If the clause is omitted,
the default is KEY IS EQUAL TO rel-key.
READ file-name [NEXT] RECORD] [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
Access Sequential files. Provides serial access.
READ file-name |NEXT |PRIOR|RECORD [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
Access Dynamic files. Provides serial access from the last Read or Start
record. PRIOR is a non-standard option; it provides access to records in
reverse sequence.
READ file-name RECORD [INTO dest-item]
INVALID KEY statements
[ELSE statements]
[END-READ]
Access Random or Dynamic files. Provides random access to the record
identified by the record number in rel-key.
REWRITE rec-name [FROM src-item]
[ INVALID KEY statements
[ELSE statements]
[END-REWRITE] ]
Access Sequential
Update the record last read. The invalid key clause is omitted.
Access Random or Dynamic
Update the record identified by rel-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.
WRITE rec-name [FROM src-item]
[ INVALID KEY statements
[ELSE statements]
[END-WRITE] ]
Access Sequential
Write a new record to the end of the file opened in Output or Extend mode.
The invalid key clause is omitted. The new record number is returned in rel-
key if it has been defined.
Access Random or Dynamic
Write a new record in the record location identified by rel-key.
The invalid key clause is mandatory. If a record already exists in the
specified location, the invalid key statements are executed.
DELETE file-name RECORD
[ INVALID KEY statements
[ELSE statements]
[END-DELETE] ]
Access Sequential
Delete the record last read. The invalid key clause is omitted.
Access Random or Dynamic
Delete the record identified by rel-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.
A typical use of this file would be for transaction records associated with a master file. The master file may be indexed or random, and the transaction file direct. The transactions for each master record could be chained; each transaction would contain the direct key of the following transaction. Such chains may be terminated by a key of low-values; no direct record has a key of this value.
Direct files may be read sequentially. If no records have been added to the file after any records have been deleted, the records will be read in the same sequence as they were added to the file. However, if records have been added after any deletions, the record sequence is undefined.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT [OPTIONAL] file-name
ASSIGN TO DISK [ORGANIZATION IS] DIRECT
| [ACCESS MODE IS SEQUENTIAL][DIRECT KEY IS dir-key] |
| ACCESS MODE IS RANDOM DIRECT KEY IS dir-key |
[FILE STATUS IS file-status] .
DIRECT KEY
A display data item of four characters defined in the program, to contain the
direct key of a record. The contents of a direct key should not be altered in
any way. When reading or writing records sequentially and the direct key is
specified, the direct key will be set to the key of the latest record
processed. When processing records randomly, the direct key specifies the
record to be read, written, rewritten or deleted.
DATA DIVISION.
FILE SECTION.
FD file-name
LABEL |RECORDS ARE|RECORD IS| STANDARD
VALUE OF FILE-ID IS file-path .
Direct file records on disk are one character longer than the defined length.
This extra character is not available to the program.
PROCEDURE DIVISION.
OPEN {| INPUT | {file-name}... }...
| OUTPUT |
| I-O |
CLOSE {file-name}...
READ file-name [[NEXT] RECORD] [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
Access Sequential files. Provides serial access.
READ file-name RECORD [INTO dest-item]
INVALID KEY statements
[ELSE statements]
[END-READ]
Access Random files. Provides direct access to the record identified by the
value in dir-key.
REWRITE rec-name [FROM src-item]
[ INVALID KEY statements
[ELSE statements]
[END-REWRITE] ]
Access Sequential
Update the record last read. The invalid key clause is omitted.
Access Random
Update the record identified by dir-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.
WRITE rec-name [FROM src-item]
Write a new record to the file in a free record location, and return the key
of the new record in dir-key, if it has been defined. If there is no room for
the record in the existing file size, the file will be extended by the length
of one record.
DELETE file-name RECORD
[ INVALID KEY statements
[ELSE statements]
[[END-DELETE] ]
Access Sequential
Delete the record last read. The invalid key clause is omitted.
Access Random
Delete the record identified by dir-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.
\COBOL12\BTRIEVEBTRIEVE files are extended as necessary to contain additonal records. They do not reduce in size as records are deleted, but the system automatically uses the deleted record areas for new records rather than extended the file.
A program with files processed by BTRIEVE contains a field which is
automatically defined by the program, in which the BTRIEVE status code is
returned after each file or transaction statement. If no exception occurs,
this field will contain zero. The field is implicitly defined as:
BTRIEVE-STATUS PIC 9999 COMP.
Relational Database Structure
For those who are unused to constructing databases with indexed sequential files, this extract from the Btrieve manual may be of assistance.
Btrieve files provide you with the underlying structures for a fully relational database. You can think of a Btrieve file as the equivalent of a table in a relational model. Your application manages relational access among its files by obtaining a value from a field in a record in one file and using that value to locate the related record in another file. This is an example of relational access in a database.
ORDER HEADER FILE Order Customer Number Number Date +-------------------------+ | 0151 | 016 | 31-01-2003 | | 0152 | 009 | 01-02-2003 | | 0153 | 045 | 03-02-2003 | +--+------+---------------+ +---------------------+ | | ORDER DETAIL FILE | CUSTOMER FILE Order Part Quantity Customer Name Address Number Number +---------------------+ +-----------------------------------+ | 0151 | 402 | 1 | | 016 | Miller, L.E. | Auckland | | 0151 | 099 | 2 | | 009 | White, D.W. | Marton | | 0152 | 256 | 5 | | 045 | Boyd, B.C. | Christchurch | | 0153 | 051 | 10 | +-----------------------------------+ +---------+-----------+ | | INVENTORY FILE Part On Number Description Hand Price +------------------------------------+ | 051 | Cassettes | 260 | 1.95 | | 099 | Diskettes | 600 | 5.95 | | 256 | Ribbons | 20 | 15.45 | | 402 | Memory board | 5 | 399.00 | +------------------------------------+
ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT [OPTIONAL] file-name ASSIGN TO DISK [ORGANIZATION IS] INDEXED | [ACCESS MODE IS SEQUENTIAL] | | ACCESS MODE IS |RANDOM|DYNAMIC| | RECORD KEY IS pri-key [ ALTERNATE RECORD KEY IS alt-key [WITH DUPLICATES] [NULL KEY IS null-char] ]... [FILE STATUS IS file-status] .RECORD KEY
The primary record key, a field defined within the file record. The key field may be display, date, or unsigned numeric. Elementary data items may be concatenated in a group data item for a multiple field key, with the exception of binary fields. The primary key may not subsequently be changed for any record, and there may not be duplicate keys or null keys.ALTERNATE RECORD KEY
An key data item providing an alternate access to the indexed records. There may be up to 7 alternate record keys in addition to the primary key. They are of the same types as primary key fields. Alternate keys may subsequently be changed for any record when the record is rewritten.
Note
WITH DUPLICATES
Alternate keys may be defined as allowing duplicates. Without this phrase,
each record in the file must have a unique key value. Records with duplicate
keys will be retrieved in the same sequence as they were originally added to
the file.
NULL KEY
Alternate keys may be defined as being omitted from an index when the contents
of the field consists entirely of the specified null-char. For binary keys,
this may be low-values for a zero key, or high-values for a key value of
65535. For packed numeric keys, this may only be low-values for a zero key.
A null key will not have an entry in the index, and the record concerned
cannot therefore be accessed via that key.
NOTE
If the file is not to be created by this program, the phrases WITH DUPLICATES and NULL KEY may be omitted. If these phrases were specified when the file was created, they will still be effective. However, all alternate keys must be defined, even if not used in this program.
DATA DIVISION. FILE SECTION. FD file-name LABEL |RECORDS ARE|RECORD IS| STANDARD VALUE OF FILE-ID IS file-path . PROCEDURE DIVISION. OPEN {| INPUT | {file-name}... }... | OUTPUT | | EXTEND | | I-O | CLOSE {file-name}... START TRANSACTIONThis statement commences the processing of a series of related operations on one or more BTRIEVE files and records. The following two statements will either confirm all operations, or will cancel all operations on the files and records affected. At least one indexed file must previously have been opened, otherwise the program will terminate with the runtime error 42.
END TRANSACTIONThis statement concludes the processing of a series of related operations on one or more BTRIEVE files and records. All changes to the files are now confirmed, and the files concerned are now released for use by other programs.
CANCEL TRANSACTIONThis statement concludes the processing of a series of related operations on one or more BTRIEVE files and records. However, all changes to the files concerned are removed and the files and records are reset to the same condition as at the start of the transaction.
START file-name [ KEY IS | EQUAL TO | |pri-key|alt-key| | = | | GREATER THAN | | > | | NOT LESS THAN | | NOT < | ] INVALID KEY statements [ELSE statements] [END-START]Access sequential or dynamic. This statement does not access a record; it defines a record from which serial access is to commence. A following READ NEXT statement will access this record. If the next statement is READ PRIOR, the record before the selected record will be accessed.
KEY
Defines the record from which access is to begin. The key is not changed by
this statement. If the clause is omitted, the default is KEY IS EQUAL TO -
key, whichever was the last key used, or the primary key if no key has yet
been used.
READ file-name [[NEXT] RECORD] [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
Access Sequential files.
Provides serial access on the current key.
READ file-name |NEXT|PRIOR| RECORD [INTO dest-item]
AT END statements
[ELSE statements]
[END-READ]
Access Dynamic files.
Provides serial access from the last Read or Start
record. PRIOR is a non-standard option; it provides for reversed record
sequence.
READ file-name RECORD [INTO dest-item]
| [KEY IS pri-key] |
| KEY IS alt-key |
INVALID KEY statements
[ELSE statements]
[END-READ]
Access Random or Dynamic files.
Provides random access to the record
identified by the referenced key, or the primary key by default.
REWRITE rec-name [FROM src-item]
[ INVALID KEY statements
[ELSE statements]
[END-REWRITE ]
Access Sequential
Update the record last read. The invalid key clause is omitted.
Access Random or Dynamic
Update the record identified by pri-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.
WRITE rec-name [FROM src-item]
INVALID KEY statements
[ELSE statements]
[END-WRITE]
Access Sequential
Write a new record to the end of the file opened in Output or Extend mode.
The primary key of the record must be greater than the preceding key in the
file. If it is not, the invalid key statements are executed.
Access Random or Dynamic
Write a new record identified by pri-key.
In all cases, if the primary key is not unique, or if an alternate key is not
unique and has not been defined with duplicates, the invalid key statements
are executed.
DELETE file-name RECORD
[ INVALID KEY statements
[ELSE statements]
[END-DELETE] ]
Access Sequential
Delete the record last read. The invalid key clause is omitted.
Access Random or Dynamic
Delete the record identified by pri-key. The invalid key clause is mandatory.
If the record is not in the file, the invalid key statements are executed.