The subroutine header information is included directly after the description of the subroutine. If more information is required about a certain routine, then examining the code is recommended.
There are several routines that are used to handle NaNs. The UNIX and VMS treatments differ but the two most important routines, that are used from MTZLIB.F, are QISNAN and QNAN. They are explained briefly below.
LRREFM must be called directly after LRREFL/LRREFF. The array LOGMSS then can be used in the program to trap for missing data. This logical array is set up by comparing the MNF set in the header with the datum. In the case of the MNF being a NaN then the datum is checked for being a NaN. You can see why it is important that the MNF must be set to a non-valid number for all data. If not, a truely measured/calculated datum maybe assign as unmeasured.
C
C ========================================
SUBROUTINE LRREFM(MINDX,LOGMSS)
C ========================================
C
C Returns Logical array which flags missing data entries
C Array DATMSS set in LRREFF and LRREFL
C
C---- Arguments :
C
C MINDX (I) INTEGER indicates which MTZ file - 1 index
C points to both input and output files
C
C LOGMSS (O) LOGICAL Array of dimension at least NPLABS(MINDX)
C containing the logical record on exit
C in lookup order
C IF LOGMSS(..) is TRUE the entry is "missing"
C Maps onto DATMSS
C
SET_MAGIC is used to change the current value of the MNF, in the header, or to assign one to an old style MTZ file. Also, it can return the MNF value. This is stored perminently in the MTZ header when the file is written out. NOTE that changing the MNF does not change the values in the data records. This must be done with RESET_MAGIC. The default is to use VAL_MAGIC = NaN
C
C ==============================
SUBROUTINE SET_MAGIC(MINDX,VAL_MAGIC,SETVAL)
C ==============================
C
C
C---- Subroutine to pass the "magic" value for this mtz file
C either into the file or back to the calling program
C
C---- Arguments :
C
C MINDX (I) INTEGER indicates which MTZ file - 1 index
C points to both input and output files
C
C VAL_MAGIC (I) REAL variable giving value assigned to
C "missing data"; it may be passed to
C an MTZ file, or return a preset value.
C
C SETVAL (I) LOGICAL if TRUE on entry, the mtz missing flag is
C set to VAL_MAGIC - ie the value in the mtz
C file is OVERWRITTEN!
C
C if FALSE on entry and there is a
C "missing value" set in the input MTZ file
C that will be returned as VAL_MAGIC, and
C SETVAL will be returned TRUE.
C
C if FALSE on entry and there is NO
C "missing value" set in the input MTZ file
C VAL_MAGIC will be set to the default
C for both input and output
C SETVAL returned TRUE
C
EQUAL_MAGIC obviously initialises an array with the missing number flag given on that unit set by SET_MAGIC. Useful when writing out data when not all the data are defined for that particular record. NOTE that the input and output files on a particular unit are treated as the same wrt missing number flags.
C
C ========================================
SUBROUTINE EQUAL_MAGIC(MINDX,ADATA,NCOL)
C ========================================
C
C Sets an array of NCOL to VAL_MISS(2,MINDX), the appropriate value
C for the output file.
C
C---- Arguments :
C
C
C MINDX (I) INTEGER indicates which MTZ file - 1 index
C points to both input and output files
C
C ADATA (I) REAL array of dimension at least NCOL
C containing the reflection record with
C "missing" values set to VAL_MAGICA
C
C
C NCOL (I) INTEGER Array size of ADATA
C
RESET_MAGIC is currently used in three ways:
C
C =============================================================
SUBROUTINE RESET_MAGIC(MINDX,ADATA,BDATA,NCOL,VAL_MAGICA,
+ VAL_MAGICB)
C =============================================================
C
C Resets an array containing Missing value flags VAL_MAGICA to
C one containing Missing value flags VAL_MAGICB
C If MINDX > 0 then VAL_MAGICA is taken to be the value of the MNF
C stored in the MTZ header, for MTZ file MINDX. Else the
C passed value is taken. The MNF pertaining to the data
C need not necessarily be the same as that stored in the
C header.
C This allows you to list arrays containing Nan entries.
C
C
C---- Arguments :
C
C
C MINDX (I) INTEGER indicates which MTZ file - 1 index
C points to both input and output files
C
C ADATA (I) REAL array of dimension at least NCOL
C containing the reflection record with
C "missing" values set to VAL_MAGICA
C
C BDATA (O) REAL Array of dimension at least NCOL
C containing the reflection record with
C "missing" values reset to VAL_MAGIC
C
C NCOL (I) INTEGER Array size of ADATA
C
C VAL_MAGICA (I/O) REAL If MINDX = 0 then this value will be
C treated as the MNF pertaining to the
C data. Otherwise
C
C VAL_MAGICB (I) REAL "Missing value" flag to reset in BDATA
C to allow record to be printed.
IS_MAGIC is used to test a datum to see whether it is a MNF. The routine works by comparing the datum with the missing number flag, if it is a number. If the missing number flag is a NaN then QISNAN is used to test the datum to see if it is a NaN. This routine is called by various other routines in MTZLIB and is used in setting up the array LOGMSS in LRREFM. It is not normally needed at the program level.
C
C =====================================
SUBROUTINE IS_MAGIC (VAL_MAGIC,VALTST,LVALMS)
C =====================================
C
C---- Function to test whether a number is "magic"
C Returns LVALMS TRUE if it is - otherwise LVALMS FALSE
C
C
C---- Arguments :
C
C VAL_MAGIC (I) REAL Missing value flag
C as "magic" for this mtz file.
C
C VALTST (I) REAL Number to test to see if it is defined
C as "magic" for this mtz file.
C
C LVALMS (O) LOGICAL Returns LVALMS TRUE if VALTST is "magic"
C FALSE if it is not, or if
C there is no "missing" number set.
C
QISNAN checks for the existance of a NaN. The UNIX version is in diskio.f and the VMS version is in vmsdiskio.for.
C_BEGIN_QISNAN C C QISNAN - check for `NaN' C C Usage: LOGICAL FUNCTION QISNAN (VALUE) C C Input: VALUE REAL value to test C C Returns .true. if VALUE is a `NaN' indicating the C absence of data. In the current implementation, this is a NaN in C IEEE or Rop on a VAX or Convex native. Any NaN (or Infinity) C will return .true. C
QNAN sets the input parameter to a NaN. The UNIX version is in library.c and the VMS version is in vmsdiskio.for.
C_BEGIN_QNAN C C QNAN - return canonical `NaN' C C Usage: SUBROUTINE QNAN (VALUE) C Output: VALUE REAL `magic' value C C Returns a `NaN' which can be used to indicate the absence C of data in an MTZ file. In the current implementation, this is a C NaN in IEEE or Rop on a VAX or Convex native. C C_END_QNAN