/*****************************************************************************
*                                                                            *
*   GETURL.SPL   Copyright (C) 2021 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns the contents of a URL                               *
*                                                                            *
*   Revisions:   20 Aug 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_GETURL

    GETURL

    Purpose: Returns the contents of a URL.

    Syntax:  GETURL("url", "targfile", "header", "typestr", "cmdtype", bufsize)

             (result, status, errmes) = GETURL("url", "targefile", "header", "typestr", "cmdtype", bufsize)

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

              "targfile" - Optional. A string, the target file name to receive
                           the contents of the URL. Defaults to "" (empty),
                           the contents are returned directly.

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

              "typestr"  - Optional. A string. The returned data type:

                              "text": return a string (default)

                            "binary": return a binary series

              "cmdtype"  - Optional A string. The HTML command. Defaults to
                           "GET".

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


    Returns: If TARGFILE is not empty, returns the full path to targfile.
             If TARGFILE is empty, directly returns a string or series,
             the value of the HTML request.

             (result, status, errmes) = GETURL("url", "", "header", "typestr", "cmdtype", bufsize)
             returns the value, integer status and error string.

    Example:
             geturl("www.dadisp.com")

             Returns the HTML text for the DADiSP home page.

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

             Returns a JSON object string from the URL. To convert the string
             to an actual object, use OBJJSONSTR:

             jobj = objjsonstr(jstr);

    Example:
             viewhtml(geturl("https://en.wikipedia.org/wiki/UTF-8", getmiscpath(1, 1) + "temp.htm"))

             Downloads the HTML contents to a temp file and displays the result.

    Remarks:
             GETURL returns the contents of the URL as specified by the
             "HEADER", "TYPESTR" and "CMDTYPE".

             If TARGFILE is empty, the result is returned directly. If
             TARGFILE is not empty, the result is written to TARGFILE.

             The result is buffered. If the result is returned directly, 
             the initial output buffer size is doubled until it fits the
             final result.

             GETURL is a low level routine for HTML data transfers.

             See WEBREADHTML to return the HTML text from a URL.

             See WEBREADIMAGE to return an image from a URL.

             See WEBREADJSON to return a JSON object from a URL.

    See Also:
             Viewhtml
             Webreadhtml
             Webreadjson
             Webreadimage
#endif

/* implemented as GETURL.DLL */