GUI ScreenIO for Windows

WebGet

This API can be used to fetch individual web pages in RAW format from web servers. You can also fetch other items from a web server such as images, documents, and other data. These files are fetched in one pass, that is, the entire document is read into memory. You are responsible to allocate the memory, and handle the information returned.

Note: This is NOT a web browser. It is a low-level web fetching utility. It is a building block, from which you could build a web browser. The GUI ScreenIO Panel Editor optionally uses this facility to check a specific web page for updates to alert users of newer versions.

Client/Server issues

This utility normally runs Client, but can be instructed to run on the server Server as follows

SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Why would you choose to run on the Client as opposed to the Server? In many cases it should not matter. When a web page is fetched from the client it will still be transmitted to the server, so there is no bandwidth saving to be had by running in either place. However, there may be times when a web page (or other file) can not be accessed by the server because it the file is located behind the client's firewall on client's local area network, or you have a reason to have this request appear to come from outside the firewall, such as wanting the web logs reflect the client as the destination as opposed to the server.

Other cases may call for fetching from the server, such as when the source is on a private web or ftp server behind the Server side firewall and you do not want to expose this server to the internet.

Files

Files available to copy to your system:

WEBGET.COB - COBOL copybook with arguments for this function
WIN32API.COB - COBOL copybook common to all APIs and functions
Sample application - Demonstrates the use of this API

Usage

     COPY WIN32API.
     COPY GETFOLDR.
     COPY WIN32API.
     COPY WEBGET.
01 MY-WEB-PAGE-BUFFER   PIC X(32000).
01 DUMMY                PIC X.
*       .
*       .
*       .
* ------------------------: Load the data specifying the request.
*                         : Note the sample text below is not
*                         : complete and serves as only one
*                         : possible way of loading the data.

MOVE 'www.screenio.com' TO WEBGET-HOST-NAME

*                         : Useful to identify your request in
*                         : Server logs. Will be appended to
*                         : "GUI ScreenIO"

     MOVE 'My Application Name' TO WEBGET-USER-AGENT
     MOVE '/index.html'      TO WEBGET-PAGE-NAME
     MOVE LENGTH OF MY-BUFFER TO WEBGET-BUFFER-SIZE
     MOVE LOW-VALUES TO MY-WEB-PAGE-BUFFER
*
* ------------------------: Call the API to GET the page
*
     SET FUNC-GETWEBPAGE TO TRUE.
     CALL 'GSWINAPI' USING WIN32API-PARMS
                           WEBGET-PARMS
                           MY-WEB-PAGE-BUFFER
                           DUMMY
                           DUMMY
                           DUMMY
                           DUMMY.
*
* ------------------------: If function failed,
*                         :   display a textual error message.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO my-error-message
       do whatever to display my-error-message.

Parameters specific to this function

WEBGET-PARMS

Specifies the server, the port, the page, and the size of the buffer for data retrieval.

MY-WEB-PAGE-BUFFER

This is an area of storage large enough to hold the item you wish to retrieve. It should be initialized prior to the call to this API because you may have to detect the end of the data retrieved by inspection. Not all web servers return the "Content-Length" header field.

Fields needed to define the retrieval:

Flag	Description
WEBGET-HOST-NAME	The undecorated host name or IP address. Do not prefix with HTTP://. Example www.myhost.com
WEBGET-USER-AGENT	When web browsers make a request, they specify their own name so that the web server can properly take advantage of the capabilities of the specific browser. This API identifies itself as GUI ScreenIO. The content of this field is appended following the trailing period. This might be useful when analyzing the servers logs.
WEBGET-BUFFER-SIZE	The size of the buffer (my-web-page-buffer in the example above). If too small an error results and data truncation occurs.
WEBGET-PORT-NUMBER	The port number for the web server. Usually 80, but private servers can be configured to listen on any port.
WEBGET-PAGE-NAME	This is the complete name of the web page, starting from the root of the server. The default page of the web server is often index.htm or index.html or default.htm. You may not need to know the exact name of the default page name and may simply specify the directory name. Examples: / (may be equivalent to /index.htm) http://www.screenio.com/gui_screenio/gs.htm

TOC

Send feedback to Norcom