X04 Chapter Contents
NAG Library Manual

# NAG Library Chapter IntroductionX04 – Input/Output Utilities

## 1  Scope of the Chapter

This chapter contains utility routines concerned with input and output to or from an external file.

## 2  Background to the Problems

### 2.1  Output from NAG Library Routines

Output from NAG Library routines to an external file falls into two categories.
 (a) Error messages which are always associated with an error exit from a routine, that is, with a nonzero value of IFAIL as specified in Section 6 of the routine document. (b) Advisory messages which include output of final results, output of intermediate results to monitor the course of a computation, and various warning or informative messages.
Each category of output is written to its own Fortran output unit – the error message unit or the advisory message unit. In practice these may be the same unit number. Default unit numbers are provided for each implementation of the Library (see the Users' Note for your implementation); they may be changed by users. Output of error messages may be controlled by the setting of IFAIL (see Section 3.3.2 in the Essential Introduction). Output of advisory messages may usually be controlled by the setting of some other parameter (e.g., MSGLVL) (or in some routines also by IFAIL). An alternative mechanism for completely suppressing output is to set the relevant unit number $\text{}<0$.
At present only formatted records are output from the Library. All formatted output to an external file from within the Library is performed by X04BAF. Similarly, all formatted input from an external file is performed by X04BBF.
When the library is being called from another language, such as C or Visual Basic, the routines X04ACF and X04ADF may be especially useful: X04ACF connects a file to a FORTRAN unit; X04ADF disconnects a file from a FORTRAN unit.

### 2.2  Matrix Printing Routines

Routines are provided to allow formatted output of
 (a) general matrices stored in a two-dimensional array (real, complex and integer data types); (b) triangular matrices stored in a packed one-dimensional array (real and complex data types); (c) band matrices stored in a packed two-dimensional array (real and complex data types).
Routines in (b) and (c) allow printing of matrices stored in formats used in particular by Chapters F06 and F07 of the Library.
By appropriate choice of arguments you can specify titles, labels, maximum output record length, and the format of individual matrix elements. All output is directed to the advisory messages unit, which may be altered by a call to X04ABF.

## 3  Recommendations on Choice and Use of Available Routines

Apart from the obvious utility of the matrix printing routines, users of the Library may need to call routines in Chapter X04 for the following purposes.
If the default error message unit (given in the Users' Note for your implementation) is not satisfactory, it may be changed to a new value NERR by the statement
```CALL X04AAF(1,NERR)
```
Similarly the advisory message unit may be changed to a new value NADV by the statement
```CALL X04ABF(1,NADV)
```
Note that both X04AAF and X04ABF use a Fortran SAVE statement to retain the value of the unit number and so neither routine is safe to use in a multithreaded environment.

## 4  Functionality Index

 Accessing external formatted file,
 reading a record X04BBF
 writing a record X04BAF
 Accessing unit number,
 of advisory message unit X04ABF
 of error message unit X04AAF
 Connecting an external file X04ACF
 Disconnecting an external file X04ADF
 Printing matrices,
 comprehensive routines,
 general complex matrix X04DBF
 general integer matrix X04EBF
 general real matrix X04CBF
 packed complex band matrix X04DFF
 packed complex triangular matrix X04DDF
 packed real band matrix X04CFF
 packed real triangular matrix X04CDF
 easy-to-use routines,
 general complex matrix X04DAF
 general integer matrix X04EAF
 general real matrix X04CAF
 packed complex band matrix X04DEF
 packed complex triangular matrix X04DCF
 packed real band matrix X04CEF
 packed real triangular matrix X04CCF

## 5  Auxiliary Routines Associated with Library Routine Parameters

 X04ACZ See the description of the argument

## 6  Routines Withdrawn or Scheduled for Withdrawal

None.

X04 Chapter Contents