/*****************************************************************************
*                                                                            *
*   XLCLEAR.SPL  Copyright (C) 2001 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Clears Excel connection established by xlget or xlput       *
*                                                                            *
*   Revisions:   22 Aug 2001  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_XLCLEAR

    XLCLEAR

    Purpose: Clears ActiveX connection to Excel established by xlget or xlput

    Syntax:  XLCLEAR(verbose)
             
             verbose - Optional integer, display any termination messages.

                         0: do not display (default)
                         1: display

    Returns: 1 if a connection existed, else 0

    Example:
             W1: rand(10, 3);

             xlput("A1:C10", W1);

             W2: xlget("A1:C10");

             xlclear

             W1 == W2 is all ones, that is W1 and W2 are equivalent. The data
             is retrieved from the current Sheet of the current Workbook.

             The Excel connection is terminated.

    Remarks:
             If Excel is visible, XLCLEAR does not terminate Excel, though
             the variables used by DADiSP are still cleared.

    See Also:
             Xlinit
             Xlget
             Xlput
             Xlsave
             Xlsaveas
#endif



/* clear Excel connection */
xlclear(verbose)
{
        local status = 0, xl;

        if (argc < 1) verbose = 0;

        /* get current excel object if any */
        xl = xlconnect(-1);

        if (isobject(xl))
        {
                status = 1;

                if (xl.visible == 0)
                {
                        /* shut down silently or not */
                        xl.displayalerts = verbose;
                        xl.workbooks.close();
                        xl.quit();
                }

                /* release excel server */
                xldisconnect();
        }

        return(status);
}