Let e-RPG do the talking

Get started using HDML to communicate with handheld devices.

This tip is an excerpt of the article "Let e-RPG do the talking" published in the July/August 2002 edition (volume

5, number 4) of the iSeries 400 Experts Journal. Provided courtesy of The 400 Group.


With the advent of new devices every day, and the advanced technology that is available in today's handheld devices (e.g. cellular phones and pagers) the need to be able to communicate with clients other than Web browsers is becoming more important, especially when users are on the run and away from the office.

The good news is that as an RPG programmer, you already have all the tools you need at your fingertips in the form of e-RPG, or writing CGI programs using the RPG programming language. And if you are already familiar with writing e-RPG programs to communicate with Web browsers, then communicating with handheld devices is as simple as changing the markup language that is used to produce output.

The standards
The standards that are used to communicate with handheld devices seem to be in constant flux, but from my research, I have found two markup languages that seem to be the standard today. Both standards are part of the Wireless Application Protocol (WAP), which is nothing more that a catch-all name for a suite of protocols (such as the two mentioned here) that allow communication via handheld devices.

The first protocol/standard is Handheld Device Markup Language (HDML). HDML was developed as a proprietary language by Openwave. Because of its proprietary nature, only handheld devices that have the Openwave browser installed are capable of viewing information formatted with the HDML markup language.

The second standard used today in the wireless world is Wireless Markup Language (WML). WML is a successor of HDML and is also fully XML compliant.

Because it is newer, not all handheld devices (such as cellular phones, pagers, etc) can accept and display information created with WML. Usually a phone that was bought a year or two ago will still be set up to use the HDML standard. But all newer phones will use the WML standard.

The good news is if you already have developed applications with HDML and want to migrate to WML, Openwave provides information on how this is done at http://developer.phone.com/technotes/hdml2wml/index.html.

There are two main points to keep in mind when developing applications for handheld devices with languages other than HTML using e-RPG.

Heads-up 1: The content type header (normally "text/html" when using HTML) will differ. Using the wrong content type will prevent your applications from functioning normally.

Heads-up 2: Second, and most obvious, is the structure of the markup language that is used. The structure of the markup language used is different in syntax than HTML. But, a few of the key components are similar, so making the transition shouldn't be difficult. Take the time to look at the specifications, examples on the web, and try things out.

In this tip we'll discuss HDML and take a look at a sample application.

HDML
When outputting dynamic HDML to a handheld device, use "Content-type: text/x-hdml" as the content type header.

The basic format of HDML that is used in application development is fairly straightforward. Each display "screen" is known as a card. When you are outputting an application that will contain more than one screen, you have the option of outputting each screen as a card inside the application or using links (similar to anchor and HREF tags in HTML).

There are benefits to each method. If the number of cards in the application is small, then it may be a better idea to simply build them all at once. This way, the user doesn't have any lag time when moving between screens. On the other hand, if the data is very sensitive (for example, inventory data on a fast moving product) then it probably is a good idea to build each card individually and use anchor type hyperlinks.

The <HDML> and </HDML> tags wrap the entire document. Inside of these wrappers will be the definitions of each card, or page. These cards are defined using the <DISPLAY> and </DISPLAY> tags.

Cards can contain text only, or actions and text. The actions that are defined on the cards will instruct the device what to do when the default key (normally the "OK" or "Accept" key) is pressed.

The best way to describe this is to show a sample application. Figure 1 contains the simple RPG code that will be used to read an item file and display items and their quantities on a handheld device using HDML.

The first thing we do is to write out the HTTP header followed by two new-line characters. This is a requirement for all CGI programs.

Next, we write out the <HDML> header tag as required. In this case we are specifying the version of 3.0. The version is required according to the specification documentation.

We then enter a loop that reads through our item file, in this case named WAPITEMPF. For each item we build a <display> section, or card. Each card is named with the item number using the name attribute of the <display> tag.

The data displayed for each item, the item number and quantity on hand, is stored in a variable named TempData. This is because we don't want to write this out just yet. You'll see that after the next read from our item file if an item is found, we write out an <action> tag. This is so that when the user pushes their "OK" button, they are taken to the next item.

The <action> tag contains a few attributes that we should discuss. First, the TYPE attribute sets which key will perform the action. The LABEL attribute sets the label that will be displayed for the key. The TASK attribute specifies the action, in which GO is used most of the time. Finally, the DEST attribute specifies where to go. So, you should be able to see why we only build this tag if another record exists in our item file.


H DFTACTGRP(*NO) BNDDIR('CGIBND')
 ****************************************************************
FWAPITEMPF IF   E           K DISK
 ****************************************************************
 * Prototypes                                                   *
 ****************************************************************
 /COPY QSRVSRC,P.HTTPSTD
 ****************************************************************
D HTTPHeader      C                   CONST('Content-type: text/x-hdml')
D NewLine         C                   CONST(X'15')
 *
D WrtDta          S           1024
D TempData        S           1024
 ****************************************************************
C                   EXSR      $One
 *
C                   SetOn                                        LR
 ****************************************************************
C     $One          BEGSR
 *
C                   eval      WrtDta = HTTPHeader +
C                                      NewLine + NewLine
C                   CallP     #WrStout(WrtDta)
 *
C                   eval      WrtDta = '<HDML VERSION=3.0>' +
C                                      NewLine
C                   CallP     #WrStout(WrtDta)
 *
C                   Read      WAPITEMPF
 *
C                   dow       (not %eof)
C                   eval      WrtDta = '<display name=' +
C                                      %trim(ITITEM) +
C                                      '>' +
C                                      NewLine
C                   CallP     #WrStout(WrtDta)
 *
C                   eval      TempData = 'Item: ' +
C                                        %trim(ITITEM) +
C                                        '<BR>' +
C                                        'QtyOH: ' +
C                                        %trim(%editc(ITQTYOH:'Z'))
C                   Read      WAPITEMPF
 *
C                   if        (not %eof)
C                   eval      WrtDta = '<action type=accept label=' +
C                                      %trim(ITITEM) +
C                                      ' task=go dest=#' +
C                                      %trim(ITITEM) +
C                                      '>' +
C                                      NewLine
C                   CallP     #WrStout(WrtDta)
C                   endif
 *
C                   eval      WrtDta = %trim(TempData) +
C                                      NewLine +
C                                      '</display>' +
C                                      NewLine
C                   CallP     #WrStout(WrtDta)
C                   enddo
 *
C                   eval      WrtDta = '</hdml>' +
C                                      NewLine
C                   CallP     #WrStout(WrtDta)
 *
C                   ENDSR

 
 
Figure 1 The source code for e-RPG program HDML1

 


<HDML VERSION=3.0>
<display name=CHAIN>
<action type=accept label=CHAINO task=go dest=#CHAINO>
Item: CHAIN<BR>QtyOH: 19
</display>
<display name=CHAINO>
<action type=accept label=CHAINOIL task=go dest=#CHAINOIL>
Item: CHAINO<BR>QtyOH: 4
</display>
<display name=CHAINOIL>
<action type=accept label=SPROCKET39 task=go dest=#SPROCKET39>
Item: CHAINOIL<BR>QtyOH: 1
</display>
<display name=SPROCKET39>
Item: SPROCKET39<BR>QtyOH: 7
</display>
</hdml>
Figure 2 The HDML source code generated by our e-RPG application

Next, we write out the TempData section containing the item number and quantity on hand for each item and close our display card using the </display> tag.

Figure 2 contains the HDML code that is outputted by this RPG application.

In Figure 2 you will notice that for each item there is a card, defined by the <display> tags. Also, every item except the last one contains an <action> tag. When this action is performed, the user is presented with the next card, which contains information about the next item.

Finally, Figure 3 contains a screen shot of the application that we just created.

Figure 3 A screen shot of our application

When the user clicks on their "OK" button, the next item and quantity will be viewed. As shown in Figure 3, the "OK" button (on this display positioned right above the SEND key) is labeled with the next available item number.

-------------------------------------
About the author: Brad Stone is the author of e-RPG: Building AS/400 Web Application with RPG. He is available for consulting, specializing in AS/400 Web application administration and programming. Visit his Web site -- www.bvstools.com -- for more information.


This was first published in January 2003

Dig deeper on iSeries CL programming

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

SearchEnterpriseLinux

SearchDataCenter

Close