DOPEN # fileNumber , fileName [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , { W | L recordLength } ] [ , ItwoChar ] [ , R ] ...

 

 

 

File input/output.  Open or create a file on a "disk" device.

 

DOPEN is a useful alternative to the standard OPEN, particularly in the case of relative (REL-type) files, and moderately useful with SEQ-type files.  Can often be forced to work with (specially hacked) DEL-type, PRG-type, and "real" USR-type files.  Almost never works with CBM-type and DIR-type files.  Never works with normally deleted (scratched files).  Does not work properly (at least for most devices) with "GEOS VLIR" USR-type files.

 

DOPEN should be used if you want to take advantage of the normally convienent (but sometimes buggy) reserved variables DS and DS$.  Unfortunately it only works with device numbers (unitNumber) from 8 to 11.  The unitNumber may actually be given multiple times, but only the last value is used; if never given, it defaults to 8.

 

The fileNumber is required and must be preceded by an octothorpe (#).  It will be needed for subsequent BASIC statements; in particular CMD/PRINT# for writing data to a file or GET#/INPUT# for reading data from a file.  In the case of relative files, the fileNumber will also be needed with RECORD.  Eventually you will (or should) use it with DCLOSE (or CLOSE).  The fileNumber can be freely choosen by the user/programmer as long as it is not in use by another currently open file [besides (D)OPEN, the BASIC statement APPEND will open a file].  However, the value should be less than 128 unless, for some reason, you want every carriage-return sent by CMD/PRINT# to have an extra line-feed character sent too (this implies writing to the file; it doesn't matter if you'll only read from the file).

 

The fileName is also required.  If it is given with zero characters, MISSING FILE NAME ERROR occurs.  If it is more than 16 characters (or more than 17 characters in the case it begins with an @ character) then STRING TOO LONG ERROR occurs.  What DOPEN (and the device) does with the fileName depends on the "open mode" (discussed below), but briefly if the name begins with @ it will be removed from the fileName sent to the device.

 

If the recordLength parameter is given, the file will usually (should) be opened in read-write mode.  This parameter is normally used to create a new relative (REL file).  It may also be used to open an existing REL file, but in this case the recordLength used in DOPEN should match the one used to create the file originally; if it does not match, the device will typically report "50, RECORD NOT PRESENT,00,00".  On some devices (like the 1571), if a non-relative file with the given fileName already exists, then the recordLength will be silently ignored and the file will be opened in read-only mode!  Attempting to specify a W parameter along with a recordLength will cause BASIC to generate SYNTAX ERROR.

 

If the W parameter is given, the file will be created and opened in write-only mode.  If the file did not previously exist, the device should not report an error.  If the file already exists and the given fileName did not begin with an @, the device will typically report "63, FILE EXISTS,00,00".  If the file already exists and fileName did begin with an @, the device will typically report "00, OK,00,00" (the existing file will be replaced); however, if the existing file is a relative file, the device will often report "64, FILE TYPE MISMATCH,00,00".  The preceding is typical behavior; some devices may not allow file replacment (no matter the exisitng file type) or they may allow relative files to be replaced.  The created (replaced) file will typically be a SEQ-type file, however most devices allow a different type to be created by adding ",type" to the end of the fileName where type is one of the characters P, S, U corresponding to PRG, SEQ, and USR file types, respectively.  However BASIC will not extend the maximum length allowed for fileName (like it does when you prepend an @).

 

If neither recordLength nor a W parameter are given, the file will typically be opened in read-only mode.  If the fileName does not exist, the device will almost always report "60, FILE NOT FOUND,00,00".  If file does exist, it will usually be opened without error unless the fileName ends with ",type" but does match type file-type in the directory (see above for paragraph for info about type) or if the type is illegal for opening as a file (for example CBM types [1581 partition] or DIR types); in such cases "64, FILE TYPE MISMATCH,00,00" is typically reported by the device.  Assuming the existing file is opened, it will actually be opened in read-write (not read-only) mode if it is a relative (REL) file.  Some devices may not support relative files at all and should report an error.

 

Because the L, W, and R characters are literal parts of the Syntax (not a variable for example), it is not possible to dynamically select an open-mode with a single DOPEN statement.  To do so, you would have to use the BASIC 1 version of OPEN or some IF/THEN/ELSE construct to select an appropriate one of several DOPEN statements.

 

If a required parameter is omitted, or an expression (enclosed in parentheses) is not valid, or an expression is used without parentheses, SYNTAX ERROR occurs.  If any parameter is not the correct type (string or numeric) a TYPE MISMATCH ERROR will be generated.  Otherwise if a parameter is not a legal value (see table above), an ILLEGAL QUANTITY ERROR is usually generated (except the previosuly described fileName).

  

Like all disk commands and statements, the Syntax is more flexible than shown above.  In particular, the parameters may be given in any order.  The general restrictions are: a comma (,) must not precede the first parameter, any non-literal value (a variable name or expression) must be enclosed in parentheses (), and do not supply the same parameter more than once.  Exceptions include the U and R parameters, which may used an unlimited number of times (R is ignored), and the twoChar parameter which must always be two literal characters (it is ignored too, but it may not be repeated).

 

Assuming the Syntax is correct, BASIC will transmit an open command to the device (this updates ST).  If the transmission does not fail (which typically generates FILE [ALREADY] OPEN or DEVICE NOT PRESENT errors) then BASIC considers the file to be open.  However, if the device reports an error (as described above or several other possibilities) then the file is not really open on the device; reading / writing the file by BASIC will generally set error bit(s) in the ST variable immediately and no data will be sent or received.  Thus it is important to check the device status via DS or DS$ after DOPEN.  If the device reports an error, you should (D)CLOSE the fileNumber in BASIC.

 

Like all disk-based commands, DOPEN restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  Like all disk-based commands, DOPEN restricts the fileName to no more than 16 characters (17 if the first is @) which makes it nearly useless if you want to include a path.

 

Like all disk-based commands, DOPEN will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to 8 if not given).

 

Examples:

DOPEN #2, "EXISTING"      : REM unit 8, drive 0; read a PRG, REL, SEQ, or USR
DOPEN #2, "EXISTING", U9  : REM unit 9, drive 0; read a PRG, REL, SEQ, or USR
DOPEN #2, "EXISTING,P"    : REM unit 8, drive 0; read a PRG-type file
DOPEN #2, "EXISTING", L64 : REM unit 8, drive 0; read or create REL file
DOPEN #2, "FRESH", W      : REM unit 8, drive 0; write/create a SEQ-type file
DOPEN #2, "@EXISTING", W  : REM unit 8, drive 0; write/replace a SEQ-type file
DOPEN #2, "FRESH,U", W    : REM unit 8, drive 0; write/create a USR-type file
DOPEN #(F),(N$),U(U)      : REM variables for fileNumber, fileName, unitNumber

 

 

APPEND, GRAPHIC, OPEN

 

CLOSE, COLLECT, DCLEAR, DCLOSE, SCRATCH 
 

CMD, DS, DS$, GET#, INPUT#, ON, PRINT#, RECORD, ST

---

© H2Obsession, 2014