OPENOUT

From BeebWiki
Jump to: navigation, search

OPENOUT is a BASIC function to open a file for output.

OPENOUT
Availability Present in BASIC I onward.
Syntax BASIC I-V <num-var> = OPENOUT(<string>)
Token (hex) BASIC I-V AE (function)
Description BASIC I-V Opens the named file for output (with OSFIND &80), returning the

file handle or zero if unable to open the file. Any pre-existing file is deleted.

Associated keywords OPENIN, OPENUP,

PTR#, EXT#, INPUT#, PRINT#, BGET#, BPUT#, EOF#, CLOSE#

Description

OPENOUT sets up the computer to work on a new file. The file's name is given as the argument; BASIC passes the name to OSFIND, which tries to create a file on the current media, and in the current directory where appropriate.

If OSFIND finds a file it deletes it. It then creates a zero-length file, opens it, assigns it a file handle and returns the handle to BASIC, which returns it as the value of OPENOUT. A file handle is an integer. 0 means the file was not found; otherwise the file handle is opaque, meaningful only to the MOS.

The file handle identifies the file while it is open, and the return value of OPENOUT must be saved and passed to all file handling statements (those whose keywords end in #.) This is because more than one file may be open at a time. Unlike other BASICs the MOS assigns file handles, not the programmer.

On opening, the pointer (PTR#) associated with the file handle is initialised to zero. All writing is done at the pointer.

If no file exists when OPENOUT is called, a default amount of space is claimed to start writing the file to:

DFS &4000
HADFS &4000
ADFS &10000

If there is a pre-existing file, then the space occupied by that file is used to write the new file to. If the programmer knows what size the written file will be it can be useful to create a dummy file of the correct size first with SAVE or CREATE before opening it.

There is inconsistancy between filing systems as to what load and execute addresses an OPENOUT file is given. Some systems set the load and execution addresses to &FFFFFFFF, some set them to 0, some leave them unchanged from any pre-existing file. If the addresses need to be set, they should be done after closing the file.

See also OSFIND on this subject.

-- jgharston 15:41, 21 July 2007 (UTC)