Open External

The Open external (OPE) statement activates a Business Rules file for input/output.

1.) When a file is opened for both SHR and INPUT, Business Rules will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

2.) The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules.

OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

3.) The WAIT specification in the OPEN statement for all physical files will now also be used as the number of seconds to wait before re-attempting to open a file that another workstation has locked. Previously it affected the wait time on locked records only. Error code 4146 will be returned if the OPEN fails due to file locking.

Comments and Examples

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

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

Using external files, a program can read or write any byte of any file including BASICA files and many others. With the exception of DELETE, the I/O statements for processing external files are the same as those used for internal files: READ, REREAD, WRITE, and REWRITE, RESTORE.

External files are record-oriented files that are not in Business Rules internal format. There is no header record with special meaning to Business Rules. There is also no delete byte embedded in the record, so the DELETE statement is not valid with an external file.

In READ, WRITE, REWRITE or RESTORE statements, the REC= or POS= parameters can be used with files opened RELATIVE to position the file pointer. Business Rules calculates the record position by multiplying the record length specified in the OPEN external statement by the record number.

For Example:

00100 Open #1: "Name=text.dat,RecL=50", External, Input, Relative
00200 RRN = 10
00300 READ #1,USING 400,REC=RRN: A$
00400 FORM C 15

After line 300 in the above example, the next sequential read would occur at the start of the next record (RRN + 1) which would be byte 501 in this example.

(NOTE that the file pointer is still at 451 for a REWRITE statement.)

The following formula calculates the starting position for the READ statement in line 300 above:

START BYTE = (INT(RRN)-1)*RECL + 1= (10 - 1)  * 50 + 1 = 451

The following example uses POS= to position a file to byte 166. It then reads a full record and assigns the first 10 bytes to A$:

00400 READ #1,USING 500,POS=166: A$
00500 FORM C 10

After line 400, the next sequential read would occur at POS + RECL. Assuming the above example uses the OPEN statement in line 100 (from the previous example), the next read position would be byte 216.

Syntax

OPEN #<file number> : {"NAME=<file ref>[, {NEW|USE|REPLACE}] [, RECL=<integer>] [, <share spec>] [, RESERVE] [, WAIT=<integer>] [, TRANSLATE=<file ref>]"|<string expression>} , EXTERNAL , {INPUT|OUTPUT|OUTIN} [, {SEQUENTIAL|RELATIVE}] [<error condition> <line ref>][,...]

Defaults

1.) Use the existing file.

2.) NOSHR.

3.) Do not reserve the file.

4.) Wait up to 15 seconds for a record.

5.) No translation.

6.) SEQUENTIAL.

7.) Interrupt the program if an error occurs and ON is not active.

Parameters

The required "file-num" parameter is a numeric expression that must equal 255 or an integer from 1 to 999, 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 resizing the main BR window), 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 external syntax; the top path will be described first:

"NAME = file-ref" is a required parameter which specifies the file or device to be opened. Using Name=save will allow the user to select a file location and name to save under. And using Name=open will allow the user to select a file to open from the standard Windows open file location window. See file-ref for more information about its syntax.

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, but a file by the specified name may not exist, in which case Business Rules will create a new file for it; so the OPEN statement needs to have the specifications for creating 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. See File I/O for more information about the NEW, USE and REPLACE parameters.

"RECL = int" is a parameter that specifies the record length and is required when creating the file for the first time. Otherwise it is not needed.

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

NOSHR (no share) indicates that the current workstation is has 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.

NOSHR should be used to prevent others from accessing a file while a program is doing a batch update, purging a file of unwanted records, or using a temporary work file.

See File Name Locking for information on the PROTECT command and the OPEN statement's RESERVE parameter; these two instructions can prevent access to a NOSHR file while it is in transition from one program or command to another.

Since NOSHR is the OPEN statement default, neglecting to specify share-spec parameters in your programs may unnecessarily limit file accessibility when the programs are installed on a multi-user system. You can easily save a great deal of future time and tedium by specifying the appropriate file-sharing standards in all your programs, even if they are currently being designed for single-user systems only.

See Record Locking for more information.

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 explicitly coding it is not necessary). SHRU operates the same as SHR, but it is used only to maintain System/23 compatibility.

SHR allow others to freely access and update the file being opened. Use of this parameter maximizes the multi-user system's capabilities; however, it also increases system overhead (see Automatic Record Locking for ideas on reducing system overhead).

Unless otherwise specified, individual records within a file that is opened for SHR,OUTIN are automatically locked as they are read. See Record Locking for more information.

SHRI allows others to use the file for input only. Others may read but not change a file opened SHRI. This parameter is useful when a program is doing batch updates or multi-record updates.

Due to potential hazards that could be caused by changes to an internal file between sorting and printing a report, ShrI is the system default for both the SORT control file and the SORT input file. As an example of such a situation, consider a report that prints a customer master file in name order. The report would either appear to be out of order or it would produce an error if another user were to change or delete a record after it was sorted and before that particular record was printed.

The SORT and INDEX utilities depend on stable input data during the sorting or indexing process. Therefore, the default for the input file is ShrI. It is possible to override the default file-sharing attribute for SORT input files. The NoShr and Shr parameters may also be specified in the FILE specification of a SORT control file. Before specifying the Shr parameter, however, you should be sure to consider the possible effects to a report program if the file is changed before or while the report is being printed.

When ShrI is specified with a file opened for INPUT, OUTPUT, or OUTIN, all subsequent OPENs must be for input only (except when using multiple index files at the same workstation). If the file was previously opened for OUTPUT or OUTIN, a file-sharing error would occur on an attempt to open with ShrI. The table below summarizes the rules and errors that can occur with various combinations of file-sharing parameters and pairs of first and second OPENs, either both from the same workstation or from two different workstations.

See Record Locking for more information.

SHRU operates the same as SHR; and is only 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. If provided, the second 256 bytes are used as an output translation table. When the output table is not provided, Business Rules constructs the output table by inverting the input translation table. See File I/O for more information about TRANSLATE=.

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 expression" (see the bottom path of the syntax diagram) parameter in place of the file identification string. The following parameter descriptions apply to all forms of the OPEN external statement, no matter which syntax path is selected.

The "EXTERNAL" keyword is required; it identifies the file being as an external 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" and "RELATIVE" are optional parameters that specify the method of access. The default is SEQUENTIAL access.

The OPEN external statement provides for error processing with the optional "error-cond line-ref" parameter. See Error Conditions for more information.

Technical Considerations

1.) Relevant error conditions are: EOF (occurs only when last record is RECL bytes long, and if a short record is found, error 4271 will occur), ERROR, EXIT, IOERR (traps short record found errors) and LOCKED.

2.) It is generally not good programming procedure to mix usage of REC= and POS= (in I/O statements) for the same external file.

3.) See Functions for more information about the REC and LREC functions. These functions can return either a record number or a byte number when specified for an external file opened RELATIVE.

4.) If the end of a file is encountered before a full record is read, Business Rules generates an incomplete record received (4271) error. Error 4271 can be trapped with an IOERR error condition. In this event, CNT is set to the number of characters read and the record is padded with null values (binary zeroes), but none of the variables in the I/O list will be modified and the file position remains the same.

After a 4271 error has occurred, a REREAD may be used to access the padded record. After this REREAD, subsequent reads will produce an end of file error (4270) instead of error 4271. If you are reading raw data the following example may be sufficient for your purposes:

03000    read #1, using Form1: RECORD$ EOF end_of_file IOERR short_rec

05000 Short_Rec: ! ***** Handle Short Record at EOF
05020    if ERR <> 4271 then goto error_trap
05040    reread #1,using Form1: RECORD$     ! Get padded short record
05060    let RECORD$=RTRM$(RECORD$,CHR$(0)) ! Remove null padding
05080    continue     ! Next read will produce EOF

5.) When a diagnostic REREAD is performed, the FORM statement should allow for a blank record. If needed, CNT should be interrogated before the REREAD, as it will be reset to the number of variables successfully formatted by the REREAD.

6.) When short records are rewritten, they are extended to RECL bytes long, thus increasing the file size. After a 4271 error, error-handling code such as the following may be used to read the bytes in a short record and rewrite them without extending the file size. In line 20000, the value of CNT (which identifies the number of data items successfully read, thus identifying the length of the short record) is assigned to C. In line 20010, the values of the LREC and RLN functions are used to determine the position of the first byte in the short record (the use of LREC in this example assumes that the last READ operation used REC= rather than POS=). In line 20020, the record length associated with the external file is assigned to the previously determined length of the short record. Line 20030 reads the entire short record, using POS= to start reading at the first byte in the record. From this point, the record can be changed and rewritten (using POS=) without extending the file size.

20000 LET C=CNT
20010 LET P=LREC(N)*RLN(N)+1   ! Complete records times record length +1
20015 ! Note- LREC provides the number of COMPLETE records in the file.
20020 RLN(N,C)                 ! Reset file N record length
20030 READ #N, POS=P: RECORD$
20040 REWRITE #N, POS=P: RECORD$

7.) See Functions for more information about the FILENUM and FILE$ functions. These functions should be especially useful for displaying messages after OPEN errors. See also the STATUS FILES command, which displays information about file opens and file reservations.

8.) The number of open files allowed by the operating system dictates the number of OPEN statements allowed in a Business Rules program.