path: root/src/hyper/pages/nagx.ht

\begin{page}{manpageXXx01}{NAG On-line Documentation: x01}
\beginscroll
\begin{verbatim}



     X01(3NAG)         Foundation Library (12/10/92)         X01(3NAG)



          X01 -- Mathematical Constants                 Introduction -- X01
                                    Chapter X01
                              Mathematical Constants

          1. Scope of the Chapter

          This chapter is concerned with the provision of mathematical
          constants required by other routines within the Library.

          It should be noted that because of the trivial nature of the
          routines individual routine documents are not provided.

          2. Background to the Problems

          Some Library routines require mathematical constants to maximum
          machine precision. These routines call Chapter X01 and thus
          lessen the number of changes that have to be made between
          different implementations of the Library.

          3. Recommendations on Choice and Use of Routines

          Although these routines are primarily intended for use by other
          routines they may be accessed directly by the user:

          Constant           Fortran Specification

          (pi)               DOUBLE PRECISION FUNCTION X01AAF(X)
                             DOUBLE PRECISION X

          (gamma)            DOUBLE PRECISION FUNCTION X01ABF(X)
          (Euler constant)   DOUBLE PRECISION X

          The argument X of these routines is a dummy argument.


          X01 -- Mathematical Constants                     Contents -- X01
          Chapter X01

          Mathematical Constants

          X01AAF  (pi)

          X01ABF  Euler's constant, (gamma)

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx02}{NAG On-line Documentation: x02}
\beginscroll
\begin{verbatim}



     X02(3NAG)         Foundation Library (12/10/92)         X02(3NAG)



          X02 -- Machine Constants                      Introduction -- X02
                                    Chapter X02
                                 Machine Constants

          1. Scope of the Chapter

          This chapter is concerned with parameters which characterise
          certain aspects of the computing environment in which the NAG
          Foundation Library is implemented. They relate primarily to
          floating-point arithmetic, but also to integer arithmetic and the
          elementary functions. The values of the parameters vary from one
          implementation of the Library to another, but within the context
          of a single implementation they are constants.

          The parameters are intended for use primarily by other routines
          in the Library, but users of the Library may sometimes need to
          refer to them directly.

          Each parameter-value is returned by a separate Fortran function.
          Because of the trivial nature of the functions, individual
          routine documents are not provided; the necessary details are
          given in Section 3 of this Introduction.

          2. Background to the Problems

          2.1. Floating-Point Arithmetic

          2.1.1.  A model of floating-point arithmetic

          In order to characterise the important properties of floating-
          point arithmetic by means of a small number of parameters, NAG
          uses a simplified model of floating-point arithmetic. The
          parameters of the model can be chosen to provide a sufficiently
          close description of the behaviour of actual implementations of
          floating-point arithmetic, but not, in general, an exact
          description; actual implementations vary too much in the details
          of how numbers are represented or arithmetic operations are
          performed.

          The model is based on that developed by Brown [1], but differs in
          some respects. The essential features are summarised here.

          The model is characterised by four integer parameters and one
          logical parameter. The four integer parameters are:

                b  :  the base

                p  :  the precision (i.e. the number of significant base-B
                      digits)

              e    :  the minimum exponent
               min

              e    :  the maximum exponent
               max

          These parameters define a set of numerical values of the form:

                                           e
                                        f*b

          where the exponent e must lie in the range [e   ,e   ], and the
                                                       min  max
          fraction f (also called the mantissa or significand) lies in the
          range [1/b,1), and may be written:

                                    f=0.f f ...f
                                         1 2    p

          Thus f is a p-digit fraction to the base b; the f  are the base-b
                                                           i
          digits of the fraction: they are integers in the range 0 to b-1,
          and the leading digit f  must not be zero.
                                 1

          The set of values so defined (together with zero) are called
          model numbers. For example, if b=10, p=5, e   =-99 and e   =+99,
                                                     min          max
                                                   67
          then a typical model number is 0.12345*10  .

          The model numbers must obey certain rules for the computed
          results of the following basic arithmetic operations: addition,
          subtraction, multiplication, negation, absolute value, and
          comparisons. The rules depend on the value of the logical
          parameter ROUNDS.

          If ROUNDS is true, then the computed result must be the nearest
          model number to the exact result (assuming that overflow or
          underflow does not occur); if the exact result is midway between
          two model numbers, then it may be rounded either way.

          If ROUNDS is false, then: if the exact result is a model number,
          the computed result must be equal to the exact result; otherwise,
          the computed result may be either of the adjacent model numbers
          on either side of the exact result.

          For division and square root, this latter rule is further relaxed
          (regardless of the value of ROUNDS): the computed result may also
          be one of the next adjacent model numbers on either side of the
          permitted values just stated.

          On some machines, the full set of representable floating-point
          numbers conforms to the rules of the model with appropriate
          values of b, p, e   , e    and ROUNDS. For example, for machines
                           min   max
          with IEEE arithmetic, in double precision:

              b    =  2

              p    =  53

              e    =-1021
               min

              e    =1024 and ROUNDS is true.
               max

          For other machines, values of the model parameters must be chosen
          which define a large subset of the representable numbers;
          typically it may be necessary to decrease p by 1 (in which case
          ROUNDS is always set to false), or to increase e    or decrease
                                                          min
          e    by a little bit. There are additional rules to ensure that
           max
          arithmetic operations on those representable numbers which are
          not model numbers, are consistent with arithmetic on model
          numbers.

          (Note: the model used here differs from that described in Brown
          [1] in the following respects: square-root is treated, like
          division, as a weakly supported operator; and the logical
          parameter ROUNDS has been introduced to take account of machines
          with good rounding.)

          2.1.2.  Derived parameters of floating-point arithmetic

          Most numerical algorithms require access, not to the basic
          parameters of the model, but to certain derived values, of which
          the most important are:

                                   (1)  1-p
          the machine precision =  (-)*b    if ROUNDS is true,
          (epsilon):               (2)

                                    1-p
                                =  b    otherwise (but see Note below).

                                    e   -1
                                     min
          the smallest positive =  b
          model number:

                                            e
                                       -p    max
          the largest positive  =  (1-b  )*b
          model number:

          Note: this value is increased very slightly in some
          implementations to ensure that the computed result of 1+(epsilon)
          or 1-(epsilon) differs from 1. For example in IEEE binary single
                                                    -24  -47
          precision arithmetic the value is set to 2   +2   .

          Two additional derived values are used in the NAG Foundation
          Library. Their definitions depend not only on the properties of
          the basic arithmetic operations just considered, but also on
          properties of some of the elementary functions. We define the
          safe range parameter to be the smallest positive model number z
          such that for any x in the range [z,1/z] the following can be
          computed without undue loss of accuracy, overflow, underflow or
          other error:

              -x

              1/x

              -1/x

              SQRT(x)

              LOG(x)

              EXP(LOG(x))

              y**(LOG(x)/LOG(y)) for any y

          In a similar fashion we define the safe range parameter for
          complex arithmetic as the smallest positive model number z such
          that for any x in the range [z,1/z] the following can be computed
          without any undue loss of accuracy, overflow, underflow or other
          error:

              -w

              1/w

              -1/w

              SQRT(w)

              LOG(w)

              EXP(LOG(w))

              y**(LOG(w)/LOG(y)) for any y

              ABS(w)

          where w is any of x, ix, x+ix, 1/x, i/x, 1/x+i/x, and i is the
          square root of -1.

          This parameter was introduced to take account of the quality of
          complex arithmetic on the machine. On machines with well
          implemented complex arithmetic, its value will differ from that
          of the real safe range parameter by a small multiplying factor
          less than 10. For poorly implemented complex arithmetic this
          factor may be larger by many orders of magnitude.

          2.2. Other Aspects of the Computing Environment

          No attempt has been made to characterise comprehensively any
          other aspects of the computing environment. The other functions
          in this chapter provide specific information that is occasionally
          required by routines in the Library.

          2.3. References

          [1]   Brown W S (1981) A Simple but Realistic Model of Floating-
                point Computation. ACM Trans. Math. Softw. 7 445--480.

          3. Recommendations on Choice and Use of Routines

          3.1. Parameters of Floating-point Arithmetic

          DOUBLE PRECISION FUNCTION returns the machine precision i.e.
          X02AJF()                  (1)  1-p                       1-p
                                    (-)*b    if ROUNDS is true or b
                                    (2)
                                    otherwise (or a value very slightly
                                    larger than this, see Section 2.1.2)

          DOUBLE PRECISION FUNCTION returns the smallest positive model
          X02AKF()                               e   -1
                                                  min
                                    number i.e. b

          DOUBLE PRECISION FUNCTION returns the largest positive model
          X02ALF()                                       e
                                                    -p    max
                                    number i.e. (1-b  )*b


          DOUBLE PRECISION FUNCTION returns the safe range parameter as
          X02AMF()                  defined in Section 2.1.2

          DOUBLE PRECISION FUNCTION returns the safe range parameter for
          X02ANF()                  complex arithmetic as defined in
                                    Section 2.1.2

          INTEGER FUNCTION X02BHF() returns the model parameter b

          INTEGER FUNCTION X02BJF() returns the model parameter p

          INTEGER FUNCTION X02BKF() returns the model parameter e
                                                                 min

          INTEGER FUNCTION X02BLF() returns the model parameter e
                                                                 max

          LOGICAL FUNCTION X02DJF() returns the model parameter ROUNDS

          3.2. Parameters of Other Aspects of the Computing Environment

          DOUBLE PRECISION FUNCTION returns the largest positive real
          X02AHF(X)                 argument for which the SIN and COS
          DOUBLE PRECISION X        routines return a result with some
                                    meaningful accuracy

          INTEGER FUNCTION X02BBF   returns the largest positive integer
          (X)                       value
          DOUBLE PRECISION X

          INTEGER FUNCTION X02BEF   returns the maximum number of decimal
          (X)                       digits which can be accurately
          DOUBLE PRECISION X        represented over the whole range of
                                    floating-point numbers

          The argument X of these routines is a dummy argument.

          4. Example Program Text

          The example program simply prints the values of all the functions
          in Chapter X02. Obviously the results will vary from one
          implementation of the Library to another.


          X02 -- Machine Constants                          Contents -- X02
          Chapter X02

          Machine Constants

          X02AHF  Largest permissible argument for SIN and COS

          X02AJF  Machine precision

          X02AKF  Smallest positive model number

          X02ALF  Largest positive model number

          X02AMF  Safe range of floating-point arithmetic

          X02ANF  Safe range of complex floating-point arithmetic

          X02BBF  Largest representable integer

          X02BEF  Maximum number of decimal digits that can be represented

          X02BHF  Parameter of floating-point arithmetic model, b

          X02BJF  Parameter of floating-point arithmetic model, p

          X02BKF  Parameter of floating-point arithmetic model, e
                                                                 min

          X02BLF  Parameter of floating-point arithmetic model, e
                                                                 max

          X02DJF  Parameter of floating-point arithmetic model, ROUNDS

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx04}{NAG On-line Documentation: x04}
\beginscroll
\begin{verbatim}



     X04(3NAG)         Foundation Library (12/10/92)         X04(3NAG)



          X04 -- Input/Output Utilities                 Introduction -- X04
                                    Chapter X04
                              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 Foundation Library Routines

          Output from NAG Foundation 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 non-zero 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); they may be changed by users. Output of error
          messages may be controlled by the setting of IFAIL (see 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 < 0.

          For further information about error and advisory messages, see
          Chapter P01.

          2.2. Matrix Printing Routines

          Routines are provided to allow formatted output of general
          rectangular or triangular matrices stored in a two-dimensional
          array (real and complex data types).

          All output is directed to the unit number for output of advisory
          messages, which may be altered by a call to X04ABF.

          3. Recommendations on Choice and Use of 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 unit number for error messages (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 unit number for advisory messages may be
               changed to a new value NADV by the statement

                     CALL X04ABF(1,NADV)

          4. Index

          Accessing unit number:
               of advisory message unit                              X04ABF
               of error message unit                                 X04AAF
          Printing matrices:
               general complex matrix                                X04DAF
               general real matrix                                   X04CAF



          X04 -- Input/Output Utilities                     Contents -- X04
          Chapter X04

          Input/Output Utilities

          X04AAF  Return or set unit number for error messages

          X04ABF  Return or set unit number for advisory messages

          X04CAF  Print a real general matrix

          X04DAF  Print a complex general matrix

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx04aaf}{NAG On-line Documentation: x04aaf}
\beginscroll
\begin{verbatim}



     X04AAF(3NAG)      Foundation Library (12/10/92)      X04AAF(3NAG)



          X04 -- Input/Output Utilities                              X04AAF
                  X04AAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X04AAF returns the value of the current error message unit
          number, or sets the current error message unit number to a new
          value.

          2. Specification

                 SUBROUTINE X04AAF (IFLAG, NERR)
                 INTEGER          IFLAG, NERR

          3. Description

          This routine enables those library routines which output error
          messages, to determine the number of the output unit to which the
          error messages are to be sent; in this case X04AAF is called with
          IFLAG = 0. X04AAF may also be called with IFLAG = 1 to set the
          unit number to a specified value. Otherwise a default value
          (stated in the Users' Note for your implementation) is returned.

          Records written to this output unit by other library routines are
          at most 80 characters long (including a line-printer carriage
          control character).

          Note that if the unit number is set < 0, no messages will be
          output.

          4. References

          None.

          5. Parameters

           1:  IFLAG -- INTEGER                                       Input
               On entry: the action to be taken (see NERR). Constraint:
               IFLAG = 0 or 1.

           2:  NERR -- INTEGER                                 Input/Output
               On entry:
                    if IFLAG = 0, NERR need not be set;

                    if IFLAG = 1, NERR must specify the new error message
                    unit number.
               On exit:
                    if IFLAG = 0, NERR is set to the current error message
                    unit number,

                    if IFLAG = 1, NERR is unchanged.
               Note that Fortran unit numbers must be positive or zero. If
               NERR is set < 0, output of error messages is totally
               suppressed.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          Not applicable.

          8. Further Comments

          The time taken by the routine is negligible.

          9. Example

          In this example X04AAF is called by the user's main program to
          make the error message from the routine DUMMY appear on the same
          unit as the rest of the output (unit 6). Normally a NAG
          Foundation Library routine with an IFAIL parameter (see Essential
          Introduction) would take the place of DUMMY.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.
\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx04abf}{NAG On-line Documentation: x04abf}
\beginscroll
\begin{verbatim}



     X04ABF(3NAG)      Foundation Library (12/10/92)      X04ABF(3NAG)



          X04 -- Input/Output Utilities                              X04ABF
                  X04ABF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X04ABF returns the value of the current advisory message unit
          number, or sets the current advisory message unit number to a new
          value.

          2. Specification

                 SUBROUTINE X04ABF (IFLAG, NADV)
                 INTEGER          IFLAG, NADV

          3. Description

          This routine enables those library routines which output advisory
          messages, to determine the number of the output unit to which the
          advisory messages are to be sent; in this case X04ABF is called
          with IFLAG = 0. X04ABF may also be called with IFLAG = 1 to set
          the unit number to a specified value. Otherwise a default value
          (stated in the User's Note for your implementation) is returned.

          Records written to this output unit by other library routines are
          at most 120 characters long (including a line-printer carriage
          control character), unless those library routines allow users to
          specify longer records.

          Note that if the unit number is set < 0, no messages will be
          output.

          4. References

          None.

          5. Parameters

           1:  IFLAG -- INTEGER                                       Input
               On entry: the action to be taken (see NADV). Constraint:
               IFLAG = 0 or 1.

           2:  NADV -- INTEGER                                 Input/Output
               On entry:
                    if IFLAG = 0, NADV need not be set;

                    if IFLAG = 1, NADV must specify the new advisory
                    message unit number.
               On exit:
                    if IFLAG = 0, NADV is set to the current advisory
                    message unit number;

                    if IFLAG = 1, NADV is unchanged.
               Note that Fortran unit numbers must be positive or zero. If
               NADV is set < 0, output of advisory messages is totally
               suppressed.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          Not applicable.

          8. Further Comments

          The time taken by this routine is negligible.

          9. Example

          In this example X04ABF is called by the user's main program to
          make the advisory message from the routine DUMMY appear on the
          same unit as the rest of the output (unit 6). Normally a NAG
          Foundation Library routine with an IFAIL parameter (see Essential
          Introduction) would take the place of DUMMY.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.
\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx04caf}{NAG On-line Documentation: x04caf}
\beginscroll
\begin{verbatim}



     X04CAF(3NAG)      Foundation Library (12/10/92)      X04CAF(3NAG)



          X04 -- Input/Output Utilities                              X04CAF
                  X04CAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X04CAF is an easy-to-use routine to print a real matrix stored in
          a two-dimensional array.

          2. Specification

                 SUBROUTINE X04CAF (MATRIX, DIAG, M, N, A, LDA, TITLE,
                1                   IFAIL)
                 INTEGER          M, N, LDA, IFAIL
                 DOUBLE PRECISION A(LDA,*)
                 CHARACTER*1      MATRIX, DIAG
                 CHARACTER*(*)    TITLE

          3. Description

          X04CAF prints a real matrix. It is an easy-to-use driver for
          X04CBF(*). The routine uses default values for the format in
          which numbers are printed, for labelling the rows and columns,
          and for output record length.

          X04CAF will choose a format code such that numbers will be
          printed with either an F8.4, F11.4 or a 1PE13.4 format. The F8.4
          code is chosen if the sizes of all the matrix elements to be
          printed lie between 0.001 and 1.0. The F11.4 code is chosen if
          the sizes of all the matrix elements to be printed lie between 0.
          001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.

          The matrix is printed with integer row and column labels, and
          with a maximum record length of 80.

          The matrix is output to the unit defined by X04ABF.

          4. References

          None.

          5. Parameters

           1:  MATRIX -- CHARACTER*1                                  Input
               On entry: indicates the part of the matrix to be printed, as
               follows:

               MATRIX = 'G' (General), the whole of the rectangular matrix.

               MATRIX = 'L' (Lower), the lower triangle of the matrix, or
               the lower trapezium if the matrix has more rows than
               columns.

               MATRIX = 'U' (Upper), the upper triangle of the matrix, or
               the upper trapezium if the matrix has more columns than
               rows. Constraint: MATRIX must be one of 'G', 'L' or 'U'.

           2:  DIAG -- CHARACTER*1                                    Input
               On entry: unless MATRIX = 'G', DIAG must specify whether the
               diagonal elements of the matrix are to be printed, as
               follows:

               DIAG = 'B' (Blank), the diagonal elements of the matrix are
               not referenced and not printed.

               DIAG = 'U' (Unit diagonal), the diagonal elements of the
               matrix are not referenced, but are assumed all to be unity,
               and are printed as such.

               DIAG = 'N' (Non-unit diagonal), the diagonal elements of the
               matrix are referenced and printed.

               If MATRIX = 'G', then DIAG need not be set. Constraint: If
               MATRIX /= 'G', then DIAG must be one of 'B', 'U' or 'N'.

           3:  M -- INTEGER                                           Input

           4:  N -- INTEGER                                           Input
               On entry: the number of rows and columns of the matrix,
               respectively, to be printed.

               If either of M or N is less than 1, X04CAF will exit
               immediately after printing TITLE; no row or column labels
               are printed.

           5:  A(LDA,*) -- DOUBLE PRECISION array                     Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the matrix to be printed. Only the elements that
               will be referred to, as specified by parameters MATRIX and
               DIAG, need be set.

           6:  LDA -- INTEGER                                         Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which X04CAF is called.
               Constraint: LDA >= M.

           7:  TITLE -- CHARACTER*(*)                                 Input
               On entry: a title to be printed above the matrix. If TITLE =
               ' ', no title (and no blank line) will be printed.

               If TITLE contains more than 80 characters, the contents of
               TITLE will be wrapped onto more than one line, with the
               break after 80 characters.

               Any trailing blank characters in TITLE are ignored.

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry MATRIX /= 'G', 'L' or 'U'.

          IFAIL= 2
               On entry MATRIX = 'L' or 'U', but DIAG /= 'N', 'U' or 'B'.

          IFAIL= 3
               On entry LDA < M.

          7. Accuracy

          Not applicable.

          8. Further Comments

          A call to X04CAF is equivalent to a call to X04CBF(*) with the
          following argument values:


                NCOLS = 80
                INDENT = 0
                LABROW = 'I'
                LABCOL = 'I'
                FORMAT = ' '


          9. Example

          This example program calls X04CAF twice, first to print a 3 by 5
          rectangular matrix, and then to print a 5 by 5 lower triangular
          matrix.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx04daf}{NAG On-line Documentation: x04daf}
\beginscroll
\begin{verbatim}



     X04DAF(3NAG)      Foundation Library (12/10/92)      X04DAF(3NAG)



          X04 -- Input/Output Utilities                              X04DAF
                  X04DAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X04DAF is an easy-to-use routine to print a complex matrix stored
          in a two-dimensional array.

          2. Specification

                 SUBROUTINE X04DAF (MATRIX, DIAG, M, N, A, LDA, TITLE,
                1                   IFAIL)
                 INTEGER              M, N, LDA, IFAIL
                 COMPLEX(KIND(1.0D0)) A(LDA,*)
                 CHARACTER*1          MATRIX, DIAG
                 CHARACTER*(*)        TITLE

          3. Description

          X04DAF prints a complex matrix. It is an easy-to-use driver for
          X04DBF(*). The routine uses default values for the format in
          which numbers are printed, for labelling the rows and columns,
          and for output record length.

          X04DAF will choose a format code such that numbers will be
          printed with either an F8.4, F11.4 or a 1PE13.4 format. The F8.4
          code is chosen if the sizes of all the matrix elements to be
          printed lie between 0.001 and 1.0. The F11.4 code is chosen if
          the sizes of all the matrix elements to be printed lie between 0.
          001 and 9999.9999. Otherwise the 1PE13.4 code is chosen. The
          chosen code is used to print each complex element of the matrix
          with the real part above the imaginary part.

          The matrix is printed with integer row and column labels, and
          with a maximum record length of 80.

          The matrix is output to the unit defined by X04ABF.

          4. References

          None.

          5. Parameters

           1:  MATRIX -- CHARACTER*1                                  Input
               On entry: indicates the part of the matrix to be printed, as
               follows:

               MATRIX = 'G' (General), the whole of the rectangular matrix.

               MATRIX = 'L' (Lower), the lower triangle of the matrix, or
               the lower trapezium if the matrix has more rows than
               columns.

               MATRIX = 'U' (Upper), the upper triangle of the matrix, or
               the upper trapezium if the matrix has more columns than
               rows. Constraint: MATRIX must be one of 'G', 'L' or 'U'.

           2:  DIAG -- CHARACTER*1                                    Input
               On entry: unless MATRIX = 'G', DIAG must specify whether the
               diagonal elements of the matrix are to be printed, as
               follows:

               DIAG = 'B' (Blank), the diagonal elements of the matrix are
               not referenced and not printed.

               DIAG = 'U' (Unit diagonal), the diagonal elements of the
               matrix are not referenced, but are assumed all to be unity,
               and are printed as such.

               DIAG = 'N' (Non-unit diagonal), the diagonal elements of the
               matrix are referenced and printed.

               If MATRIX = 'G', then DIAG need not be set. Constraint: If
               MATRIX /= 'G', then DIAG must be one of 'B', 'U' or 'N'.

           3:  M -- INTEGER                                           Input

           4:  N -- INTEGER                                           Input
               On entry: the number of rows and columns of the matrix,
               respectively, to be printed.

               If either of M or N is less than 1, X04DAF will exit
               immediately after printing TITLE; no row or column labels
               are printed.

           5:  A(LDA,*) -- COMPLEX(KIND(1.0D)) array                  Input
               Note: the second dimension of the array A must be at least
               max(1,N).
               On entry: the matrix to be printed. Only the elements that
               will be referred to, as specified by parameters MATRIX and
               DIAG, need be set.

           6:  LDA -- INTEGER                                         Input
               On entry:
               the first dimension of the array A as declared in the
               (sub)program from which X04DAF is called.
               Constraint: LDA >= M.

           7:  TITLE -- CHARACTER*(*)                                 Input

               On entry: a title to be printed above the matrix. If TITLE =
               ' ', no title (and no blank line) will be printed.

               If TITLE contains more than 80 characters, the contents of
               TITLE will be wrapped onto more than one line, with the
               break after 80 characters.

               Any trailing blank characters in TITLE are ignored.

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry MATRIX /= 'G', 'L' or 'U'.

          IFAIL= 2
               On entry MATRIX = 'L' or 'U', but DIAG /= 'N', 'U' or 'B'.

          IFAIL= 3
               On entry LDA < M.

          7. Accuracy

          Not applicable.

          8. Further Comments

          A call to X04DAF is equivalent to a call to X04DBF(*) with the
          following argument values:


                NCOLS = 80
                INDENT = 0
                LABROW = 'I'
                LABCOL = 'I'
                FORMAT = ' '
                USEFRM = 'A'


          9. Example

          This example program calls X04DAF twice, first to print a 4 by 3
          rectangular matrix, and then to print a 4 by 4 lower triangular
          matrix.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.


\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx05}{NAG On-line Documentation: x05}
\beginscroll
\begin{verbatim}



     X05(3NAG)         Foundation Library (12/10/92)         X05(3NAG)



          X05 -- Date and Time Utilities                Introduction -- X05
                                    Chapter X05
                              Date and Time Utilities

          1. Scope of the Chapter

          This chapter provides routines to obtain the current real time,
          and the amount of processor time used.

          2. Background to the Problems

          2.1. Real Time

          Routines are provided to obtain the current time in two different
          formats, and to compare two such times.

          2.2. Processor Time

          A routine is provided to return the current amount of processor
          time used. This allows the timing of a particular routine or
          section of code.

          3. Recommendations on Choice and Use of Routines

          X05AAF     returns the current date/time in integer format.

          X05ABF     converts from integer to character string date/time.

          X05ACF     compares two date/time character strings.

          X05BAF     returns the amount of processor time used.


          X05 -- Date and Time Utilities                    Contents -- X05
          Chapter X05

          Date and Time Utilities

          X05AAF  Return date and time as an array of integers

          X05ABF  Convert array of integers representing date and time to
                  character string

          X05ACF  Compare two character strings representing date and time

          X05BAF  Return the CPU time

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx05aaf}{NAG On-line Documentation: x05aaf}
\beginscroll
\begin{verbatim}



     X05AAF(3NAG)      Foundation Library (12/10/92)      X05AAF(3NAG)



          X05 -- Date and Time Utilities                             X05AAF
                  X05AAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X05AAF returns the current date and time.

          2. Specification

                 SUBROUTINE X05AAF (ITIME)
                 INTEGER          ITIME(7)

          3. Description

          X05AAF returns the current date and time as a set of seven
          integers.

          4. References

          None.

          5. Parameters

           1:  ITIME(7) -- INTEGER array                             Output
               On exit: the current date and time, as follows:

               ITIME(1) contains the current year.

               ITIME(2) contains the current month, in the range 1--12.

               ITIME(3) contains the current day, in the range 1--31.

               ITIME(4) contains the current hour, in the range 0--23.

               ITIME(5) contains the current minute, in the range 0--59.

               ITIME(6) contains the current second, in the range 0--59.

               ITIME(7) contains the current millisecond, in the range 0--
               999.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          The accuracy of this routine depends on the accuracy of the host
          machine. In particular, on some machines it may not be possible
          to return a value for the current millisecond, for example. In
          this case, the value returned will be zero.

          8. Further Comments

          None.

          9. Example

          This program prints out the vector ITIME after a call to X05AAF.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.
\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx05abf}{NAG On-line Documentation: x05abf}
\beginscroll
\begin{verbatim}



     X05ABF(3NAG)      Foundation Library (12/10/92)      X05ABF(3NAG)



          X05 -- Date and Time Utilities                             X05ABF
                  X05ABF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X05ABF converts from a seven-integer format time and date, as
          returned by X05AAF, into a character string, returned via the
          routine name.

          2. Specification

                 CHARACTER*30 FUNCTION X05ABF (ITIME)
                 INTEGER          ITIME(7)

          3. Description

          X05ABF returns a character string of length 30 which contains the
          date and time as supplied in argument ITIME. On exit, the
          character string has the following format:


                `DAY XXTH MTH YEAR HR:MN:SC.MIL',


            where  DAY   is one of 'Sun', 'Mon', 'Tue', 'Wed', 'Thu',
                         'Fri', 'Sat',

                   XX    is an integer denoting the day of the month,

                   TH    is one of 'st', 'nd', 'rd', 'th',

                   MTH   is one of 'Jan', 'Feb', 'Mar', 'Apr', 'May',
                         'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',

                   YEAR  is the year as a four digit integer,

                   HR    is the hour,

                   MN    is the minute,

                   SC    is the second,

                   MIL   is the millisecond.

          If on entry the date in ITIME is invalid, the string returned is

          4. References

          None.

          5. Parameters

           1:  ITIME(7) -- INTEGER array                              Input
               On entry: a date and time in the format returned by X05AAF,
               as follows:
                   ITIME   must contain the year as a positive integer.
                   (1)

                   ITIME   must contain the month, in the range 1-12.
                   (2)

                   ITIME   must contain the day, in the range 1 to p, where
                   (3)     p = 28, 29, 30 or 31, depending on the month and
                           year.

                   ITIME   must contain the hour, in the range 0-23.
                   (4)

                   ITIME   must contain the minute, in the range 0-59.
                   (5)

                   ITIME   must contain the second, in the range 0-59.
                   (6)

                   ITIME   must contain the millisecond, in the range 0-
                   (7)     999.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          The day name included as part of the character string returned by
          this routine is calculated assuming that the date is part of the
          Gregorian calendar. This calendar has been in operation in Europe
          since October the 15th 1582, and in Great Britain since September
          the 14th 1752. Entry to this routine with a date earlier than
          these will therefore not return a day name that is historically
          accurate.

          8. Further Comments

          Two dates stored in character string format, as returned by this
          routine, may be compared by X05ACF.

          9. Example

          This program initialises a time in ITIME, and converts it to
          character format by a call to X05ABF.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.
\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx05acf}{NAG On-line Documentation: x05acf}
\beginscroll
\begin{verbatim}



     X05ACF(3NAG)      Foundation Library (12/10/92)      X05ACF(3NAG)



          X05 -- Date and Time Utilities                             X05ACF
                  X05ACF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X05ACF compares two date/time character strings, each stored in
          the format returned by X05ABF.

          2. Specification

                 INTEGER FUNCTION X05ACF (CTIME1, CTIME2)
                 CHARACTER*(*)    CTIME1, CTIME2

          3. Description

          X05ACF compares two date/time character strings, and returns an
          integer that specifies which one is the earliest. The result is
          an integer returned through the routine name, with meaning as
          follows:

               X05ACF = -1: the first date/time string is earlier than the
               second.

               X05ACF = 0: the two date/time strings are equivalent.

               X05ACF = 1: the first date/time string is later than the
               second.

          4. References

          None.

          5. Parameters

           1:  CTIME1 -- CHARACTER*(*)                                Input

           2:  CTIME2 -- CHARACTER*(*)                                Input
               On entry: the date/time strings to be compared. These are
               expected be in the format returned by X05ABF, although
               X05ACF will still attempt to interpret the strings if they
               vary slightly from this format. See Section 8 for further
               details.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          Not applicable.

          8. Further Comments

          For flexibility, X05ACF will accept various formats for the two
          date/time strings CTIME1 and CTIME2.

          The strings do not have to be the same length. It is permissible,
          for example, to enter with one or both of the strings truncated
          to a smaller length, in which case missing fields are treated as
          zero.

          Each character string may be of any length, but everything after
          character 80 is ignored.

          Each string may or may not include an alphabetic day name, such
          as 'Wednesday', at its start. These day names are ignored, and no
          check is made that the day name corresponds correctly to the rest
          of the date.

          The month name may contain any number of characters provided it
          uniquely identifies the month, however all characters that are
          supplied are significant.

          Each field in the character string must be separated by one or
          more spaces.

          The case of all alphabetic characters is insignificant.

          Any field in a date time string that is indecipherable according
          to the above rules will be converted to a zero value internally.
          Thus two strings that are completely indecipherable will compare
          equal.

          According to these rules, all the following date/time strings are
          equivalent:

              'Thursday 10th July 1958 12:43:17.320'

              'THU 10th JULY 1958 12:43:17.320'

              '10th Jul 1958 12:43:17.320'

          9. Example

          This program initialises two date/time strings, and compares them
          by a call to X05ACF.


          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

\end{verbatim}
\endscroll
\end{page}
\begin{page}{manpageXXx05baf}{NAG On-line Documentation: x05baf}
\beginscroll
\begin{verbatim}



     X05BAF(3NAG)      Foundation Library (12/10/92)      X05BAF(3NAG)



          X05 -- Date and Time Utilities                             X05BAF
                  X05BAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          X05BAF returns the amount of processor time used since an
          unspecified previous time, via the routine name.

          2. Specification

                 DOUBLE PRECISION FUNCTION X05BAF ()

          3. Description

          X05BAF returns the number of seconds of processor time used since
          some previous time. The previous time is system dependent, but
          may be, for example, the time the current job or the current
          program started running.

          If the system clock of the host machine is inaccessible for any
          reason, X05BAF returns the value zero.

          4. References

          None.

          5. Parameters

          None.

          6. Error Indicators and Warnings

          None.

          7. Accuracy

          The accuracy of the value returned depends on the accuracy of the
          system clock on the host machine.

          8. Further Comments

          Since the value returned by X05BAF is the amount of processor
          time since some unspecified earlier time, no significance should
          be placed on the value other than as a marker to be compared with
          some later figure returned by X05BAF. The amount of processor
          time that has elapsed between two calls of X05BAF can be simply
          calculated as the earlier value subtracted from the later value.

          9. Example

          This program makes a call to X05BAF, performs some computations,
          makes another call to X05BAF, and gives the time used by the
          computations as the difference between the two returned values.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.
\end{verbatim}
\endscroll
\end{page}