/*****************************************************************************
*                                                                            *
*   WEBREADFILE.SPL   Copyright (C) 2021 DSP Development Corporation         *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Saves the contents of a URL to a file.                      *
*                                                                            *
*   Revisions:   21 Nov 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_WEBREADFILE

    WEBREADFILE

    Purpose: Saves the contents of a URL to a local file.

    Syntax:  WEBREADFILE("url", "targfile", "header", bufsize)

              "url"      - A string, the source URL address.

              "targfile" - A string, the target file name to receive
                           the contents of the URL.

              "header "  - Optional. A string, the HTML header string. Defaults to empty,
                           no header.

              bufsize    - Optional. An integer. The initial size of the HTML
                           transfer buffer. Defaults to 65536.


    Returns: A string, the full path to TARGFILE.

    Example:
             webreadfile("https://www.dadisp.com", getmiscpath(1, 1) + "temp.html")

             Saves the HTML text for the DADiSP home page to the file
             "temp.htm" located in the local temp folder.

    Example:
             viewfile(webreadfile("https://www.dadisp.com", getmiscpath(1, 1) + "temp.html"))

             Same as above except the HTML text is displayed from the temporary file.

    Example:
             url  = "http://dummy.restapiexample.com/api/v1/employees";
             hed  = "Content-Type: application/json" + strescape("\r\n");
             tmpf = getmiscpath(1, 1) + "temp.html"

             jobj = readjson(webreadfile(url, tmpf, hed));

             Returns a JSON object from the URL by copying the JSON string
             to a temporary file and reading the file as a JSON object.

    Remarks:
             WEBREADFILE saves the contents of the URL to the specified
             local file name.

             See WEBREADSTR to directly return a string from a URL.

             See WEBREADBINARY to directly return a series from a URL.

    See Also:
             Readjson
             Viewhtml
             Webreadbinary
             Webreadstr
#endif


/* save contents of URL to a local file */
webreadfile(url = "", targfile = "", header = "", bufsize = 0)
{
        local s;

        if (strlen(url) == 0 || strlen(targfile) == 0)
        {
                error(sprintf("%s - input URL and Target File Name Required", __FUNC__));
        }

        /* low level URL getter, returns filename */
        s = geturl(url, targfile, header, bufsize);

        return(s);
}