by Don Draper
Powersoft's Internet Developer Toolkit (IDT) offers PowerBuilder developers a powerful and easy way to create dynamic content for the Web. Dynamic content includes any information which might change based on some action or choice by the user. For example, a user could ask for list of hotels in a specific area or an inventory report. The IDT offers this popular capability to PowerBuilder developers right now. The ability to generate dynamic content on the Web is currently one of the most sought after skills. The IDT and Web.PB bring this ability to PowerBuilder developers by allowing them to use the powerful and familiar reporting features of PowerBuilder.
Introduction
This article will discuss coding techniques you can use in your Distributed PowerBuilder (DPB) methods for dynamic reporting of data. More specifically, I will focus on techniques for returning data to the Web browser from a DPB method called through Web.PB. Since DPB is where much of the work is done, PowerBuilder developers will feel at home. I will assume you are somewhat familiar with the IDT product. If not, I refer you to Arthur Hefti's article titled "Internet Developers Toolkit for PowerBuilder 5.0" in the March 1997 issue of PowerTimes for an excellent review of this product. Also, I will be presenting three sessions at the Swiss Conference '97 all related to PowerBuilder and the Internet so don't miss them if you want to learn more.
Web.PB
First, allow me to briefly introduce Web.PB, an important part of the IDT product. Web.PB is a simple program. It has no visual interface and works as a client to a Distributed PowerBuilder program. It also communicates directly with Web servers. It accomplishes this by using a standard process called Common Gateway Interface (CGI). CGI defines how external programs may communicate with a Web server. Programs utilizing CGI can process data coming into a Web server from a Web browser such as Netscape Navigator or Microsoft Internet Explorer. They may also send data back to the Web browser through the Web server. This is where developers write logic that provides dynamic content to Web browsers.
Web.PB becomes the interface between a Web server and a DPB application. When the Web server receives a request for data from a DPB application, it hands the data off to Web.PB which then calls the DPB method, directly passing any arguments if applicable. Web.PB must reside on the same computer as the Web server, but the DPB application may be located elsewhere on the network. Once the DPB method is finished, it RETURNS data as either a string or blob data type back to Web.PB. That in turn passes it back to the Web server. The Web server then adds any necessary header information to the data before passing it back to the Web browser. Figure 1 shows how the data flows in such a request.
Calling the DPB Method
The call to a DPB method through Web.PB is created using standard Hypertext Markup Language (HTML) tags known as FORM and Anchor. Detailing this aspect of Web.PB is beyond the scope of this article. However, in an attempt to provide some level of continuity to my train of thought, I've included a simple FORM example. The following HTML fragment would create a form containing a single line edit control where the user could enter a customer number. The form includes a button labeled "Retrieve" which calls the DPB method named of_getcust, passing it the entered number. The of_getcust method is located in non-visual object (NVO) called n_cst_reports inside a DPB application named pbserver. Can you guess the name of the argument defined in the of_getcust method that will receive the customer number? Hint: It must exactly match the corresponding field name desginated as INPUT NAME.
<FORM METHOD=GET
ACTION="/pbcgi050.exe/pbserver/n_cst_reports/of_getcust">
Enter Customer No. <INPUT NAME="custno">
<INPUT TYPE="SUBMIT" VALUE="Retrieve">
</FORM>
Inside the DPB Method
Once inside the DPB method, PowerBuilder developers may use familiar tools such as the datastore and Powerscript. This is where the PowerBuilder developer becomes a CGI programmer. Powerscript actually helps create the content that the Web browser will receive. For example, the datastore can convert its data into a string formatted with HTML by simply referencing a datastore attribute called HTMLTable. The reference may use the new dot notation syntax or the older Describe function.
ls_html = ds.Object.DataWindow.Data.HtmlTable
..or..
ls_html = ds.Describe("DataWindow.Data.HtmlTable")
RETURN ls_html
By ending the DPB method with a "RETURN ls_html", the contents of the datastore are returned to the Web browser and will appear in tabular format for browsers which support the HTML Table extensions. This is a very powerful feature for returning tabular data from a database to a Web browser. Since plain HTML is returned, any Web browser will be able to view the information and no other plug-ins or software are needed.
When a DPB method returns a string to Web.PB, Web.PB assumes HTML is
being returned to the browser and will prefix the data with an appropriate HTTP header.
The header identifies the data to the browser as HTML and looks like "Content-type:
text/html~r~n". The browser uses this HTTP header to determine what type of data it
is receiving. Data that contains only text or HTML tags may be returned as a string from
DPB methods to Web.PB.
HTML May Need Assistance
Regular HTML may not be suitable for all of your reporting needs. Perhaps your target users are inside a corporate Intranet and you can ensure that the browsers are equipped with appropriate plug-ins to process and display your reports. This might include using Powersoft's datawindow plug-in that permits PSR reports to be viewed inside a Web browser. The user can see report detail including graphs which would be impossible using HTML alone.
Another popular report or document format includes Adobe Acrobat's Portable Document Format (PDF). PDF files can present static documents such as catalogs, office forms or even replicas or your PowerBuilder reports. My session on using Adobe's PDF will show ways to convert your datawindow reports directly into PDF format as the report is requested. The PDF format is fast becoming a Web standard and Adobe provides a free and powerful plug-in which works with most popular Web browsers and on almost all platforms.
This type of reporting usually involves binary information that resides locally in a file (such as REPORT.PSR or INVENTORY.PDF). There are two main approaches for returning binary data of this nature:
- The Web server returns the file to the browser
- The DPB method returns the file to the browser
First, let's discuss two techniques that force the Web server to send the file back to the browser. Later, I'll provide a third technique for sending the file directly from Web.PB.
Web Server Returns File - EMBED
The DPB method returns a string containing the HTML tag for EMBED. This tag defines a file name and other attributes that include the height and width that the data may occupy inside the client area of the browser. Here is an example of returning a string with an EMBED tag.
RETURN "<EMBED SRC=/scripts/report.psr WIDTH=400 HEIGHT = 500>"
Once the browser receives this HTML, it would request the file referenced in the SRC attribute from the Web server. The Web server would then send the file to the browser and add all appropriate HTTP headers. The browser uses the WIDTH and HEIGHT attributes to reserve space in the client area where the PSR will display. The browser must be equipped with the Powersoft datawindow plug-in to properly process and display the PSR report. This example represents the simplest form of returning an EMBED tag; only the PSR would display on the Web page. However, the returning string could contain other HTML tags and other referenced objects such as text and graphics. All the rules for HTML page formatting would apply.
This technique will also work for returning documents in Adobe Acrobat's popular PDF format. Like the datawindow plug-in for the PSR report, the browser must also be equipped with an appropriate plug-in for displaying PDF documents. When using the EMBED tag to display a PDF file, only the first page will display in the client area specified by the WIDTH and HEIGHT attributes. The user must right click the mouse for a popup menu that permits them to fully activate the PDF plug-in inside the browser. The fully activated plug-in takes up the entire client area (or current frame if activated in an HTML frame) and provides the Web user with a complete toolbar for manipulating the PDF document including zoom, print, save the PDF to a local file and more. Depending on your needs, you may prefer to have the PDF document display with the PDF plug-in fully activated with a toolbar. This will require the second technique.
Web Server Returns File - Redirection
To have the browser request a file from the Web server but avoid the characteristics caused by the WIDTH and HEIGHT attributes for the EMBED tag, a technique known as "redirection" may be used. CGI programs sometimes use redirection to instruct a browser to request a different HTML page. For example, older browsers that cannot view HTML TABLE formatted data may get "redirected" to a similar page that does not contain HTML TABLE tags. The redirection is simply a reference to a new location and resource called a Uniform Resource Locator (URL). The URL could point to a page on a completely different Web server or another page on the same server.
The redirection command is actually another HTTP header. Since Web.PB automatically prefixes an HTTP Header section to data returned as a string data type, a string will not suffice. The the only other valid data type accepted by Web.PB must be used; the blob data type. Typically, when we return a blob data type to Web.PB, the developer is responsible for prefixing the appropriate HTTP header for "Content-type:" to describe the type of data sent back to the browser. However, in this special case, we are just returning an HTTP header with out any data. The HTTP header will instruct the browser to redirect itself to the new URL. For our current reporting need, we redirect the browser to our PSR file.
lb_blob = blob("Location: /scripts/report.psr~r~n~r~n")
RETURN lb_blob
The "Location" header directs the browser to request the file from the Web server similar to the EMBED tag. This may work best for files where the display should not be limited to the area defined by the WIDTH and HEIGHT attributes of the EMBED tag. In fact, this method works great when returning PDF files to a browser. The PDF plug-in on the browser is immediately activated taking up the entire client area and provides the user with a tool bar. The user is not required to right mouse click in order to see the toolbar or subsequent pages of the PDF document.
Notice in the example that I did not include the full URL of "http://myhost.com/scripts/report.psr". The full URL is only be required if the file existed on a different host computer. Also note the pair of carriage return linefeeds at the end of the URL. HTTP header entries are always separated by a single carriage return - linefeed with a blank line signaling the last header entry and the beginning of the data. A blank line (the pair of carriage return, linefeeds) must follow our HTTP header to signal the end of the HTTP header section even though no data follows. This is an easy mistake for new CGI programmers to make.
Also, when a blob is returned from a DPB method, Web.PB will continue
to call the same method until we return a null or 0 length blob. Therefore, the DPB method
must contain logic that determines the initial call to our method and returns a null blob
when it is finished sending our blob data to Web.PB. There are plenty of examples with the
IDT that show how to handle the multiple calls from Web.PB
DPB Method Returns File
Another technique requires the DPB method to return the file. Here, the method must return a blob data type to Web.PB. The DPB method takes the responsibility of returning the data to Web.PB instead of the Web server. This method provides ultimate flexibility and reduces network traffic by eliminating the need to send an intermediate string or blob to the Web browser. Since it is returning the raw data directly to the browser as a blob, it must include the appropriate HTTP header to identify the type of data. This is done by prefixing the data with two HTTP header entries. The first header identifies the type of the data being returned using the "Content-type:" header. Two possible headers for content type include:
Content-type: application/psr~r~n // for PSR files
..or..
Content-type: application/pdf~r~n // for PDF files
The browser will parse the header to determine how to process the incoming data. In our examples, the browser will invoke the appropriate plug-in to display the data. The second header provides the length of the raw data to the browser (file length only). The entire header section for returning a PSR file might appear as follows:
blob_header = blob("Content-type: application/psr" + "~r~n")
blob_header += blob("Content-length: ") + blob(string(flen)) +
blob("~r~n~r~n")
The flen variable may be determined using the Powerscript FileLength function. Following the HTTP headers and the blank line will be the raw data from the PSR or PDF file. On the initial call to the DPB method it open the file and load the entire contents into a blob variable. Since the FileRead( ) function can only read 32K at a time, it is usually included in a loop.
DO WHILE i_bytes_read >= 0
i_bytes_read = FileRead(ii_fnum, blob_part) // load next 32k of file (or null if
EOF)
blob_data = blob_data + blob_part
LOOP
This blob variable which holds the data from the file is then appended to the blob variable holding the headers and returned to Web.PB.
blob_complete = blob_header + blob_data
RETURN blob_complete
Powersoft provides sample code demonstrating this technique for returning image files. However, it works for any type of binary data as long as you prefix the data with the appropriate content type header. We'll explore this in more detail in my session on reporting with Adobe's PDF so I hope you can attend. I'll be available to discuss these topics (and others) during the conference, so please don't hesitate to find me and ask questions. Also, if you are considering using Web.PB for future Web work, you will not want to miss my next article in PowerTimes on using Netscape Cookies with Web.PB for state management! Happy CGI programming!