\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}