View source for 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>,}]
[[Image:Openexternal.png|900px]]

===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. 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}}

{{:SHR}}

{{:SHRI}}

{{:SHRU}}

"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.<br>
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.


<noinclude>
[[Category:Statements]]
[[Category:File Processing Statements]]
</noinclude>