/*****************************************************************************
*                                                                            *
*   WEBREADSTR.SPL   Copyright (C) 2021 DSP Development Corporation          *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns the contents of a URL as a string.                  *
*                                                                            *
*   Revisions:   21 Nov 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_WEBREADSTR

    WEBREADSTR

    Purpose: Returns the contents of a URL as a string.

    Syntax:  WEBREADSTR("url", "header", bufsize)

             (str, retval, errmes) = WEBREADSTR("url", "header", bufsize)

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

              "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 contents of the URL.

             (str, retval, errmes) = WEBREADSTR("url", "header", bufsize)
             returns the string result, the result status and an error
             message (if any).

    Example:
             webreadstr("https://www.dadisp.com")

             Returns the HTML text for the DADiSP home page.

    Example:
             viewtext(webreadstr("https://www.dadisp.com"))

             Same as above, except the return text is displayed.

    Remarks:
             WEBREADSTR returns the contents of the URL directly.

             See WEBREADBINARY to directly return a series from a URL.

             See WEBREADFILE to save the contents of a URL to a local file..

    See Also:
             Viewhtml
             Webreadbinary
             Webreadfile
#endif


/* return the contents of URL as a string */
webreadstr(url = "", header = "", bufsize = 0)
{
        local str, retval, errmes;

        if (strlen(url) == 0)
        {
                error(sprintf("%s - input URL Required", __FUNC__));
        }

        if (outargc > 1)
        {
                (str, retval, errmes) = geturl(url, "", header, "text", bufsize);

                return(str, retval, errmes);
        }
        else
        {
                str = geturl(url, "", header, "text", bufsize);

                return(str);
        }
}