OPEN Statement (File I-O) ---------------------------------------------------------------------------- Action Enables I-O to a file, device, or ISAM table. Syntax 1 OPEN file$ FOR mode ACCESS access lock AS # filenumber% LEN= reclen% OPEN database$ FOR ISAM tabletype tablename$ AS # filenumber% Syntax 2 OPEN mode$, # filenumber%, file$, reclen% Remarks You must open a file before any I-O operation can be performed on it. OPEN allocates a buffer for I-O to the file or device and determines the mode of access used with the buffer. The OPEN statement uses the following arguments. ----------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- file$ A filename or path. mode A keyword that specifies one of the following file modes. Random, Argument Description ---------------------------------------------------------------------------- the following file modes. Random, Binary, Input, Output access A keyword that specifies the operation performed on the open file. lock A keyword that specifies the lock type. filenumber% An integer expression with a value between 1 and 255, inclusive. When an OPEN statement is executed, the file number is associated with the file as long as it is open. Other I-O statements may use the Argument Description ---------------------------------------------------------------------------- Other I-O statements may use the number to refer to the file. reclen% For random-access files, the record length; for sequential files, the number of characters buffered. The reclen% is an integer expression less than or equal to 32,767 bytes. database$ A database filename or path. tabletype The name of a type of table defined using the TYPE statement. tablename$ The name of the ISAM table being opened. It follows the ISAM naming conventions (listed later in this entry). Argument Description ---------------------------------------------------------------------------- entry). Syntax 1 The arguments file$ and database$ specify an optional device, followed by a filename or path conforming to the DOS file-naming conventions. The argument database$ must be the name of an ISAM file. For sequential files, if file$ does not exist, it is created when opening a file for anything but input [mdash] that is, OUTPUT, RANDOM, BINARY, and APPEND. For ISAM, a nonexistent database$ or tablename$ is created only when using the PROISAMD library; with the PROISAM library, BASIC generates the error message File Not Found if database$ or tablename$ does not exist. The argument mode is a keyword that specifies one of the following file modes. ----------------------------------------------------------------------------- Keyword Description ---------------------------------------------------------------------------- Random Specifies random-access file mode, the default mode. In random mode, if no ACCESS clause is present, three attempts are made to open the file when the OPEN statement is executed. Access is attempted in the following order. 1. Read and write 2. Write only 3. Read only Binary Specifies binary file mode. In binary mode, you can read or write Keyword Description ---------------------------------------------------------------------------- binary mode, you can read or write information to any byte position in the file using GET and PUT. In binary mode, if no ACCESS clause is present, three attempts are made to open the file, following the same order as for random files. Input Sequential input mode. Output Sequential output mode. Append Sequential output mode. Sets the file pointer to the end-of-file and the record number to the last record of the file. A PRINT # or WRITE # statement then extends Keyword Description ---------------------------------------------------------------------------- WRITE # statement then extends (appends to) the file. If the mode argument is omitted, the default random-access mode is assumed. The argument access is a keyword that specifies the operation performed on the opened file. If the file is already opened by another process and the specified type of access is not allowed, the OPEN operation fails and BASIC generates the error Permission denied. The ACCESS clause works in an OPEN statement only if you are using a version of DOS that supports networking (DOS version 3.0 or later). In addition, you must run the SHARE.EXE program (or the network startup program must run it) to perform any locking operation. If ACCESS is used with OPEN, earlier versions of DOS return the error message Feature unavailable. The argument access can be one of the following. ----------------------------------------------------------------------------- Access type Description ---------------------------------------------------------------------------- Read Opens the file for reading only. Write Opens the file for writing only. Read Write Opens the file for both reading and writing. This mode is valid only for random and binary files, and files opened for append. The lock clause works in a multiprocessing environment to restrict access by other processes to an open file. The argument can be one of the following keywords specifying the lock type. ----------------------------------------------------------------------------- Lock type Description ---------------------------------------------------------------------------- Shared Any process on any machine may read from or write to this file. Do not confuse the shared lock type with the SHARED statement or the shared attribute that appears in other statements. Lock Read No other process is granted read access to this file. This access is granted only if no other process has a previous read access to the file. Lock Write No other process is granted write access to this file. This lock is granted only if no other process Lock type Description ---------------------------------------------------------------------------- granted only if no other process has a previous write access to the file. Lock Read Write No other process is granted either read or write access to this file. This access is granted only if read or write access has not already been granted to another process, or if a lock read or lock write is not already in place. If you do not specify a lock type, the file may be opened for reading and writing any number of times by this statement, but other operations are denied access to the file while it is opened. When OPEN is restricted by a previous process, BASIC generates error 70, Permission denied. The argument reclen% is an integer expression less than or equal to 32,767 bytes. It specifies different settings for random-access or sequential files. ----------------------------------------------------------------------------- For random-access. For sequential files. ---------------------------------------------------------------------------- The argument reclen% sets the The argument reclen% specifies the record length (the number of number of characters to be loaded characters in a record). into the buffer before the buffer is written to, or read from, the disk. The default is 128 bytes. A larger buffer means more room taken from BASIC, but faster file I-O. A smaller buffer means more room in memory for BASIC, but slower I-O. For random-access. For sequential files. ---------------------------------------------------------------------------- I-O. The default is 512 bytes. The LEN clause and reclen% are ignored if mode is binary. For sequential files, reclen% need not correspond to an individual record size, because a sequential file may have records of different sizes. ISAM is a keyword that specifies you are opening an ISAM table. The argument tabletype is the name of a user-defined type that defines a subset of the table definition. (See the entry for the TYPE statement.) The argument tablename$ is the name of the ISAM table being opened. It follows the ISAM naming conventions. - It has no more than 30 characters. - It uses only alphanumeric characters (A-Z, a-z, 0-9). - It begins with an alphabetic character. - It includes no BASIC special characters. Syntax 2 In the second (alternative) form of the OPEN syntax, mode$ is a string expression that begins with one of the following characters and specifies the file mode. ----------------------------------------------------------------------------- Mode Description ---------------------------------------------------------------------------- O Sequential output mode. I Sequential input mode. Mode Description ---------------------------------------------------------------------------- I Sequential input mode. R Random-access file I-O mode. B Binary file mode. A Sequential output mode. Sets the file pointer to the end of the file and the record number to the last record of the file. A PRINT # or WRITE # statement extends (appends to) the file. Note This alternative syntax does not support any of the access and file-sharing options found in the primary syntax. It is supported for compatibility with programs written in earlier versions of BASIC. The following devices are supported by BASIC and can be named and opened with the argument file$. KYBD, SCRN, COM n, LPT n, CONS, PIPE. The BASIC file I-O system allows you to take advantage of user-installed devices. (See your DOS manual for information on character devices.) Character devices are opened and used in the same manner as disk files. However, characters are not buffered by BASIC as they are for disk files. The record length for device files is set to 1. BASIC sends only a carriage return at the end of a line. If the device requires a line feed, the driver must provide it. When writing to device drivers, keep in mind that other BASIC users will want to read and write control information. Writing and reading of device-control data is handled by the IOCTL statement and IOCTL$ function. None of the BASIC devices directly supports binary mode. However, line-printer devices can be opened in binary mode by adding the BIN keyword. OPEN "LPT1.BIN" FOR OUTPUT AS #1 Opening a printer in binary mode eliminates printing a carriage return at the end of a line. When you open an ISAM table, the next record is the first record in the table and the current index is the null index. Any ISAM operation that closes a table causes transactions to be committed. For example, if a type mismatch occurs while you are opening an ISAM table, the table is closed and a pending transaction is committed. You may wish to code your programs so they first open all tables, then perform all transactions, then close tables. Make sure any operation that can close a table occurs outside a transaction. Note In input, random-access, and binary modes you can open a file under a different file number without first closing the file. In output or append mode you must close a file before opening it with a different file number. See Also CLOSE, FREEFILE, TYPE Example See the FREEFILE function programming example, which uses the OPEN statement.