Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_file_open (x04ac)

## Purpose

nag_file_open (x04ac) opens a Fortran unit number for reading, writing or appending, and associates the unit with a named file.

## Syntax

[ifail] = x04ac(iounit, file, mode)
[ifail] = nag_file_open(iounit, file, mode)

## Description

nag_file_open (x04ac) is especially useful if the calling language is not Fortran. It opens a Fortran unit number for reading, writing or appending, and associates the unit with a filename specified by the argument file.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{iounit}$int64int32nag_int scalar
The Fortran unit number which identifies the file to be read from, written to or appended to. Note that this may be system dependent. Values in the range $7$ to $1000$ should however be safe on most systems.
2:     $\mathrm{file}$ – string
The name of the file to be opened.
Constraint: must contain a valid filename for the computer system being used.
3:     $\mathrm{mode}$int64int32nag_int scalar
Specifies whether the file is to be opened for reading, writing or appending.
${\mathbf{mode}}=0$
The file is to be opened for reading.
${\mathbf{mode}}=1$
The file is to be opened for writing.
${\mathbf{mode}}=2$
The file is to be opened for appending.
Constraint: $0\le {\mathbf{mode}}\le 2$.

None.

### Output Parameters

1:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
On entry, mode is invalid.
${\mathbf{ifail}}=2$
Failure to open the file for reading.
${\mathbf{ifail}}=3$
Failure to open the file for writing.
${\mathbf{ifail}}=4$
Failure to open the file for appending.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

This example illustrates how to open a file for writing.
```function x04ac_example

fprintf('x04ac example results\n\n');

file = 'success.res';

% Associate unit number iounit=4 with filename success.res
iounit = int64(4);

% Open File for writing to
mode = int64(1);
[ifail] = x04ac(iounit, file, mode);

% write to file here via iounit using x04ba
fprintf('The file named %s was opened for writing on unit number %d\n\n', ...
file,iounit);

% Close File associated with unit number iounit=4
fprintf('Unit number %d has been closed\n', iounit);

delete(file);

```
```x04ac example results

The file named success.res was opened for writing on unit number 4

Unit number 4 has been closed
```