/*****************************************************************************
*                                                                            *
*   SAVEDS.SPL  Copyright (C) 2014 DSP Development Corporation               *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Saves multi-column series to a dataset                      *
*                                                                            *
*   Revisions:   23 Jan 2014  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_SAVEDS

    SAVEDS

    Purpose: Saves all columns of a series to a dataset.

    Syntax:  SAVEDS(s, "dsname", "sername")

                       s - A series, the multi-column series to save.

                  dsname - Optional. A string, the Dataset name. Defaults to
                           "ds".

                 sername - Optional. A string, the Series name. Defaults to
                           "ch". Each column will be saved to series "ch1",
                           "ch2" ... "chN".

               overwrite - Optional. An integer, the overwrite existing
                           series flag. Defaults to 1, overwrite if
                           series already exists.

    Returns:
             An integer, the number of saved series if successful.

    Example:
             W1: randn(100, 3)
             saveds(w1);
             
             Saves the 3 columns of W1 to "ds.1.ch1", "ds.1.ch2 and
             "ds.1.ch3". If the dataset "ds" already exists, the version
             number is set to the next available version.

    Example:
             W1: randn(100, 3)
             saveds(w1, "Testdrive.5", "Axel");
             
             Same as above, except the 3 columns of W1 are saved as
             "Testdrive.5.Axel1", "Testdrive.5.Axel2 and "Testdrive.5.Axel3".

    Remarks:
             SAVEDS saves all the columns of a series to a dataset.
             The series number is appended to the template series name.

             If the Dataset name includes a version number in the form
             of "dsname.ver" where dsname is the Dataset name and ver
             is the integer version number, the series are all saved to
             the specifed version.

             If a version number is not specified in the Dataset name,
             the series are saved in a new version of the Dataset using
             the next available version number.

             A version number of -2 also implies next version.

             A version of -3 implies save the series in the last
             version of the Dataset.

             A version of 0 implies save the series in the first
             version of the Dataset.

   See Also:
             Loaddataset
             Saveseries
#endif


saveds(s, dsname, sname, overwrite)
{
        local nc, ver, j, cmd;

        if (argc < 4)
        {
                if (argc < 3)
                {
                        if (argc < 2)
                        {
                                if (argc < 1) error("saveds - input series required");

                                dsname = "ds";
                        }

                        sname = "ch";
                }

                overwrite = 1;
        }

        nc = numcols(s);

        /* massage series name */
        sname = strextract(sname, 1, 14);

        /* save first one */
        saveseries(col(s, 1), sprintf("%s.%s1", dsname, sname), overwrite);

        /* save remaining to same version */
        ver = strget(2, dsname, ".");

        if (strlen(ver) > 0)
        {
                ver = castint(ver);
        }
        else
        {
                /* last version */
                ver = -3;
        }

        /* build single saveseries command */
        cmd = "saveseries(";

        /* columns */
        loop (j = 2..nc)
        {
                cmd += sprintf("col(s, %d),", j);
        }

        /* dataset.ver.series names */
        loop (j = 2..nc)
        {
                cmd += sprintf('"%s.%d.%s%d",', dsname, ver, sname, j);
        }

        cmd += sprintf("%d)", overwrite);

        /* run saveseries function */
        eval(cmd);
}