------------
MADIS Errors
------------

MADIS errors are reported via text messages written to standard output (for the
dump programs, and for user-written programs that have selected this option), 
and via status code values returned from MADIS subroutines to user-written 
programs (with status code 0 for success).  The text messages include the name 
of the routine reporting the error as well as the error itself.


Invalid Inputs (1-1000)
-----------------------

These can result from invalid specifications in dump program parameter files or 
in user-written programs.  To resolve the error, refer to the appropriate 
*dump_usage.txt file or the *dump.f code (and additional documentation referred 
to there).

STATUS Code   Note  Message
-----------   ----  -------
1                   Invalid time window (MINFWD < MINBCK)
2                   Time window too large (more than 3h)
3                   Invalid window record type
4                   Invalid time
5                   Reserved                   
6                   Invalid QC type
7                   Invalid domain type
8                   Invalid domain arguments
9                   Invalid correction type
10                  Invalid database 
11             1    Invalid latitude for selected domain
12                  Invalid time translation format
13                  Invalid variable code [specific variable code]
14             2    Too many records requested

Notes
-----

1.  The invalid latitude for selected domain error occurs if a station's
    latitude meets these criteria:

    - Lambert conformal map projection, with a Northern hemisphere tangent,
      and the station latitude is at the South Pole; or a Southern hemisphere 
      tangent is being used and a station appears at the North Pole.

    - Polar stereographic map projection, with a station at the South Pole.

    (You can still use the data, but you can't get its I,J grid coordinate.)

2.  The too many records requested error occurs if the time window and domain
    filtering selections result in more station records than can be handled 
    internally by the subsystem.  The user should restructure the request 
    (e.g., use a smaller time window and get the data in two chunks).

    Here are the record limits for each subsystem:

      SFC       300000
      RAOB        1000
      NPN          160
      ACARS      60000
      ACARSP      1000
      HYDRO      15000
      MAP         2000
      RDMTR       1800
      SATWND     60000
      SATSND     80000
      SATRAD     80000
      SNOW       20000
      WISDOM     50000

Run-time Environment (1001-2000)
--------------------------------

STATUS Code   Note  Message
-----------   ----  -------
1001           1    MADIS_STATIC environment variable not defined
1002           1    MADIS_STATIC directory path too long
1003           1    MADIS_DATA environment variable not defined
1004           1    MADIS_DATA directory path too long
1005           2    Variable not in selected database
1006           3    No data for [specific nominal time]
1007           4    MADIS_SERVER_ROOT environment variable not defined
1008           4    MADIS_SERVER_ROOT directory path too long

Notes
-----

1.  MADIS requires two environment variables:  MADIS_STATIC points to the
    static directory in the directories where MADIS is installed, and MADIS_DATA
    points to the top of the directory tree where the MADIS data files are 
    stored.  See the INSTALL.* files for information on how to set environment 
    variables on your system.

2.  The variable not in selected database error will occur if you try to read an 
    AWIPS-only variable using the FSL database, or an FSL-only variable using
    the AWIPS database.  See *variable_list.txt for a list of what variables
    exist in the different databases.

3.  The no data error occurs when there is nothing to return.  This can occur
    when you call M*STA to load in data for a given nominal time, or it can
    happen when you ask for an individual variable.  In either event, this is
    a "normal" error return and no corrective action needs to be taken.

4.  The MADIS_SERVER_ROOT environment variable is only used on the MADIS web
    server.


System Failures (2001-3000)
---------------------------

STATUS Code   Note  Message
-----------   ----  -------
2001           1    BAD [specific netCDF I/O error message]
2002           2    BIF - [specific bad internal file I/O error message]

Notes
-----

1.  In general, you shoudn't get any I/O errors reading netCDF files using the
    MADIS programs and library routines.  However, this can conceivably happen 
    if a data file gets corrupted.  If the problem persists over time, please 
    send a bug report to the MADIS development team (see the last section
    below).

    Also, if you're using a very old version of the netCDF library, you may get
    a netCDF "variable not found" error when you should really get a MADIS 
    "variable not in selected database" error.

2.  If a bad internal file I/O error occurs, it may also be a sign that disk 
    files have become corrupted.  The BIF errors involve MADIS internal files
    in the static directory.  Generally, the routine reporting the error will
    use a code name to indicate the file.  Here's the list of files that can
    be affected:

    Code          True Name (in static directory)
    ----          ---------
    SFCTBL        sfctbl.txt
    UAPTTBL       acarstbl.txt      (whichever subsystem you were accessing)
                  awips_acarstbl.txt
                  acarsptbl.txt
                  awips_acarsptbl.txt
                  npntbl.txt
                  raobtbl.txt
                  rdmtrtbl.txt
    HYDROTBL      hydrotbl.txt
    SATRADTBL     satradtbl.txt
    SATSNDTBL     satsndtbl.txt
    SATWNDTBL     satwndtbl.txt
    VCNTBL        acarsvcn.txt      (whichever subsystem you were accessing)
                  acarspvcn.txt
                  hydrovcn.txt
                  npnvcn.txt
                  raobvcn.txt
                  rdmtrvcn.txt
                  satradvcn.txt
                  satsndvcn.txt
                  satwndvcn.txt
                  sfcvcn.txt
    STADIC        stadic.txt
    SUBSRCIN      sfcsrcin.txt
    TOPMINI       topomini.txt

    The netCDF template files used by MADIS can also be affected.  In this case,
    the full name and path of the file will be in the error message.  (This is
    because these files may either be in the static directory or may be part of
    an AWIPS system and external to MADIS.)

    You can try to resolve the problem by examining the file, by loading in a
    backup copy from offline storage, reinstalling MADIS, etc.  If the problem
    persists, please send a bug report to the MADIS developers.


Programming Errors (3001-4000)
------------------------------

In addition to the errors in the above categories, these errors can occur
with user-written MADIS programs.  

STATUS Code   Note  Message
-----------   ----  -------
3001           1    Invalid subsystem    
3002           2    Selected subsystem not initialized - [specific subsystem]
3003           3    Time not initialized by [specific M*STA routine]
3004           4    Invalid variable data type
3005           5    No subsystem has been initialized

Notes
-----

1.  An invalid subsytem error occurs when an invalid character string is sent
    into MINIT.

2.  A subsystem-specific routine (e.g., MSETSFCPVDR) has been called without
    first initializing the subystem with MINIT.

3.  An MGET* call to retrieve a variable has been made without first calling
    the corresponding M*STA routine to load in the stations for the desired
    nominal time.

4.  An invalid variable data type error occurs when a numeric MGET* routine
    is called to read a character variable, or a character MGET* routine has
    been asked to read a numeric variable.

5.  A general-purpose MADIS selection routine (e.g., MSETWIN) has been called
    without first initializing any subsystem.


MADIS Internal Errors (4001-5000)
---------------------------------

STATUS Code   Note  Message
-----------   ----  -------
4001           1    Exceeded internal array size
4002           1    INTV - [Specific invalid internal variable message]

1.  Internal limitations have been exceeded or logic errors have been detected.  
    Please send a bug report with as much information as possible to the MADIS 
    development team (and accept our apologies):

       madis-support@noaa.gov


   
