
>>>>>>>>>>>>>>>>>>> FILE: ../varlist/varlist.f <<<<<<<<<<<<<<<<<<<

C===============  VARLIST:  Variable List Input Package  ===============
C
C  This package of routines provides a facilty for the free-format entry
C  of input variables by name.  This facility is similar to the NAMELIST
C  input capability provided by some compilers, but it has several
C  important improvements: inputs can originate from multiple sources,
C  such as from a file and the keyboard; comments can be included;
C  inputs can start in any column; the NAMELIST name &xxxx and end
C  marker &END are not needed; special formats such as time/date are
C  supported; and the optional dump of input values is more readable.
C
C  The VARLIST package is accessed via the following routines:
C
      SUBROUTINE VLDEF ( LIN)
      CHARACTER*(*)      LIN
C
C     SUBROUTINE VLADD ( LIN, LPOS, ERR)
      INTEGER            LPOS, ERR
C
C     SUBROUTINE VLRDD ( NAM, DVAR, FND)
      CHARACTER*(*)      NAM
      DOUBLE PRECISION   DVAR(*)
      LOGICAL            FND
C
C     SUBROUTINE VLRDI ( NAM, IVAR, FND)
      INTEGER            IVAR(*)
C
C     SUBROUTINE VLRDL ( NAM, LVAR, FND)
      LOGICAL            LVAR(*)
C
C     SUBROUTINE VLRDC ( NAM, CVAR, FND)
      CHARACTER*(*)      CVAR(*)
C
C     SUBROUTINE VLRDT ( NAM, EPOCH, DVAR, FND)
      DOUBLE PRECISION   EPOCH
C
C     SUBROUTINE VLDMP ( U)
      INTEGER            U
C
C     SUBROUTINE VLCLR
C
C-----------------------------------------------------------------------
C  VLDEF (VarList DEFine) is used to define the names, dimensions, and
C  types of the input variables.  (Defining types is optional: if you do
C  not define types, type checking is not performed.)  The definitions
C  are passed to VLDEF via a string, within which the definitions appear
C  in free format, separated by commas and/or spaces.  Each definition
C  contains the name of the variable and its dimensions, if it is an
C  array, followed by an optional type specifier consisting of a colon
C  and type letter.  The variable name can be lower or uppercase.  If it
C  is an array, dimension information must be specified: subscript
C  limits are specified the same way as in a FORTRAN specification
C  statement (ie, the lower limit is optional, but if specified, is
C  separated from the upper limit by a colon); up to 7 subscripts may
C  be specified.  The type letter indicates the input format expected
C  for the variable, as follows: F for floating point (either single or
C  double precision), I for integer, U for unsigned integer, L for
C  logical, C for character string, and T for time/date format.  The
C  type letter can be in either upper or lowercase.  Long definition
C  strings can be split up into pieces, if desired, with a separate call
C  to VLDEF for each piece: the definitions simply accumulate in an
C  internal buffer.  If any input variables are defined via VLDEF, then
C  all variables must be defined, and variables which appear in the
C  input without having been defined are flagged as erroneous.  If VLDEF
C  is never called at all, however, all variable names are allowed.
C
C  Input Arguments:
C   LIN    String containing VARLIST definitions.
C
C  Output Arguments: none
C
C  Example:  CALL VLDEF( 'AB:f XY(5):f CD:i EF:c GH')
C   This call defines AB, XY, CD, EF, and GH as varlist variables.
C   Spaces have been used instead of commas to separate the definitions.
C   Type checking will ensure that AB and XY receive floating point
C   values, CD receives an integer value, and EF receives a character
C   string (of any length).  No type checking is performed on GH.
C
C-----------------------------------------------------------------------
C  VLADD (VarList ADD inputs) is used to add a string of variable
C  assignments to the internal varlist save area.  The input strings are
C  obtained by the calling routine, which typically reads them as lines
C  from a file or from the keyboard.  VLADD is called for each input
C  record.  Assignments can continue from one input string to the next;
C  even a list of constants can continue on the next string.  (If you
C  want to ensure that a string starts with a new assignment, call VLNEW
C  before calling VLADD.)  VLADD parses the input string, checks
C  subscripts if present, ensures values match the variable types, and
C  saves the inputs in an internal save area.  Comments are allowed in
C  the input string: all characters after '!' are ignored.  If an error
C  occurs, a message is printed along with a pointer to the location of
C  the problem in the input string.  Note that if an error occurs, any
C  inputs to the right of it are ignored. The argument LPOS indicates
C  whether the input string already appears on the user's screen, and if
C  so, in which print position it starts.  LPOS is used only in the
C  aligning of the error pointer.
C
C  Input Arguments:
C   LIN   String containing free-format inputs to Varlist variables.
C   LPOS  If the string LIN is on the screen, specify the column in
C         which it starts; if the string is not on the screen, specify
C         0 to cause it to be printed should an error occur.
C
C  Output Arguments:
C   ERR   Error indicator.  If no error occurred, ERR = 0.
C
C  Note: VLADD can be used to delete variable assignments: you simply
C        assign null values to them.  For example, the following
C        sequence deletes any previously-specified values for variables
C        AB and XY:
C           CALL VLADD( 'AB=XY=', ERR)
C           CALL VLNEW
C
C-----------------------------------------------------------------------
C  VLRDD (VarList ReaD Double)
C  VLRDI (VarList ReaD Integer)
C  VLRDL (VarList ReaD Logical)
C  VLRDC (VarList ReaD Character)
C  VLRDT (VarList ReaD Time)
C
C  Each of these routines searches for the specified name in the
C  variable list save area, and reads the associated value(s) into the
C  variable itself.  If a value was not specified in the varlist, the
C  variable is not changed.  If the variable was declared as an array,
C  all values specified in the varlist for that variable are read into
C  the array; elements which were not assigned values are not changed.
C  The output parameter FND is set to TRUE if any values were read into
C  the variable, and FALSE if no values were specified for the
C  variable.  The routine VLRDT has an additional input argument, which
C  is a reference Julian date, and the output value(s) in DVAR are
C  in days relative to this epoch.
C
C  Inputs:
C   NAM    Variable name.
C   EPOCH  Reference Julian date, for call to VLRDT.
C
C  Outputs:
C   xVAR   Variable: x = D for double precision, I for integer, L for
C          logical, or C for character.
C   FND    Set to TRUE if values were read into the variable.
C
C-----------------------------------------------------------------------
C  VLDMP (VarList DuMP) dumps the variable list to the specified output
C  unit.  Each variable is dumped on a separate line.  The dump provides
C  a convenient summary of the user's inputs.  Only those variables and
C  values actually specified in the input strings are dumped.  The
C  values of numeric constants are shown exactly as they were entered by
C  the user (ie, the same number of significant digits are shown).
C
C  Inputs:
C   U   I/O unit number to be used for the dump.
C
C-----------------------------------------------------------------------
C  VLCLR (VarList CLeaR) clears the variable list save area.
C
C$----------------------------------------------------------------------
