Function:     dcdset

Purpose:      Decodes a string denoting a set and optional subsets into
              subset levels. The set MUST exist!

Category:     USER IO

File:         dcdset.c

Author:       K.G. Begeman

Call:         dcdset_struct *dcdset( char *string )

              dcdset returns a pointer to a dcdset_struct in static
              memory. The dcdset_struct is defined in dcdsetdef.h.

              typedef struct {
                 char setname[FILENAME_MAX+1]; // name of set
                 fint *subsets;                // decoded subset levels
                 fint status;                  // return status
              } dcdset_struct;

              The return status can be one of the following:

               >0  Number of subsets decoded.
               -1  Input string longer than internal buffer.
               -2  Empty input string.
               -3  Set does not exist.
               -4  Set name too long for buffer.
               -5  Could not allocate memory to contain axis info.
               -6  Axis name not unique.
               -7  Integer number expected.
               -8  Syntax error.
               -9  Could not allocate memory for storing grids positions.
              -10  Repeat argument <= 0.
              -11  Loop increment is 0.
              -12  Infinite loop.
              -13  Internal inconsistency.
              -14  Axis already defined.
              -15  Non existent subset.
              -16  Could not allocate memory for storing subset levels.

Warning:      dcdset closes the set before returning. This invalidates
              the internal set handle which then cannot be used anymore
              instead of the set name.
              For the FITS pseudo sets supported by GIPSY's Python binding,
              this behaviour has been suppressed, i.e sets which have the
              string "_tmp_" in their name are not closed.

Related Docs: dcdsetdef.dc3

Updates:      Nov 28, 1993: KGB, Document created.
              Feb  9, 2009: JPT, Added warning in document.
              Feb 18, 2009: JPT, Conditionally suppress set closing.