Node:Rewrite, Next:RmDir, Previous:ReturnAddress, Up:Reference

### Rewrite

(Under construction.)

#### Synopsis

    procedure Rewrite (var F: any_file; [FileName: String;]
                                        [BlockSize: Cardinal]);

#### Description

`Rewrite` opens a file for writing. If the file does not exist, it is created. The file pointer is positioned at the beginning of the file.

Like `Reset`, `Append` and `Extend` do, `Rewrite` accepts an optional second and third parameter.

The second parameter can specify the name of the file in the filesystem. If it is omitted, the following alternative ways can be used to specify the name. There are so many different ways in order to be compatible to the idiosyncrasies of as many other Pascal compilers as possible. (If you know about yet other ways, let us know ...)

- The `Assign` procedure (see Assign)
- The `Bind` procedure (see Bind)

The following ways are only available if the file is external, i.e. a global variable which is mentioned in the program header. Otherwise, the file will be internal, i.e. get no name in the file system (it may get a name temporarily, but will then be erased automatically again). This is useful to store some data and read them back within a program without the need for permanent storage.

- A command-line parameter of the form `--gpc-rts=-nf:name` where f is the identifier of the file variable.
- If the file was mentioned in the program header and the option `--transparent file names` (see GPC Command Line Options) was set, the file name will be identical to the identifier converted to lower-case.
- Otherwise, the user will be prompted for a file name.

The last optional parameter determines the block size of the file. It is valid only for untyped files. Almost always, 1 is the most reasonable value here. However, the existence of this parameter is a BP compatibility feature, and in BP it defaults to 128 because of historic misdesign. Therefore, GPC requires this parameter to be present. In `--borland-pascal` mode, it makes it optional (like BP does), but warns about the strange default if omitted.

#### Conforming to

`Rewrite` is defined in ISO 7185 Pascal. The `BlockSize` parameter is a Borland Pascal extension. The `FileName` parameter is a GNU Pascal extension.

#### Example

    program RewriteDemo;
    var
      Sample: Text;
    begin
      Assign (Sample, 'sample.txt');
      Rewrite (Sample);
      WriteLn (Sample, 'Hello, World!');
      Close (Sample)
    end.

#### See also

Assign, Reset, Append, Extend, Update.