How to create a dropdown list in Mobile RPG

The DDSList is a frequently-used user interface control for Mobile RPG. It has four distinct “personalities”:

1. A navigation list (which provides a scrolling list with lots of options).
2. A radiobutton list (which provides a radiobutton list that accepts multiple choices).
3. A checkbox list (which provides a checkbox list that accepts one choice).
4. A dropdown list (which provides a single-select dropdown)

This article discusses how to use the DDSList control to provide a dropdown element for a Mobile RPG record format. When rendered this way, the runtime HTML is a select tag with option tags for each item in the dropdown list. This article’s example code is shown below in Figure 1a. When the OK button is clicked the selected value of the dropdown is shown in the textbox just above the OK button.

Figure 1a. The DDSList rendered as a dropdown (select tag)

The rendered dropdown control is populated with columns in an RPG subfile. The properties of the DDSList specify the field names and other subfile attributes. The list in Figure 1b below shows the DDSList properties, and their values, used in this example to render the dropdown.

Figure 1b. DDSList properties used in this example to render the dropdown.

The code below in Figure 1c shows how this DDSList looks in the ASPX markup:

 <mdf:DdsList ID="DdsList1" runat="server" 
    CssClass="DdsList" CssClassChevron="DdsListChevron" 
    CssClassDetail="DdsListDetail" CssClassIcon="DdsListIcon" 
    CssClassImage="DdsListImage" CssClassList="DdsListList" 
    CssClassRow="DdsListRow" 
    ListType="Dropdown" 
    ClearIndicator="99" 
    SelectedField="DDSel" 
    SelectedItemField="DDCurrVal" 
    SubfileName="sbfDD" 
    SubfileControlName="sbfDDCtl" 
    TextField="DDText" 
    TextFieldLength="24" 
    ValueField="DDValue" 
    ValueFieldLength="2" 
/>

Figure 1c. The DDSList as defined in the ASPX markup.

To fully understand the relationship between a Mobile RPG control and its underlying RPG program, it often helps to save the corresponding DDS source while exporting the Mobile RPG display file to the IBM i. Do this by using the options in the red box below in Figure 1d.

Figure 1d. How to save the DDS source when exporting a Mobile RPG display file to the IBM i

The DDSList dropdown’s exported DDS source is shown below in Figure 1e. This source lets you clearly see that there are three columns in the subfile (two of which are hidden).

The DDRList’s SelectField property produces the DDSEL field. For most subfile-driven Mobile RPG controls, this field is set to “1” when a row is selected and READC is used to read the selected rows. Because the DDSList’s dropdown only ever has a single selected value, the DDSList’s SelectedItemField specifies an RPG field that is a getter and setter for the dropdown’s value. As you can see in the DDS source in the figure below, the property this field produces (DDCURRVAL) is hidden. The DDSList’s dropdown logic automatically puts the dropdown’s selected value in this field. If you set this field in your RPG to a value in the list before showing the page, the list will be positioned at that value’s list position.

A            DDCURRVAL      2A  H
A            STATE         10A  B  1  6
A          R SBFDD                     SFL
A            DDSEL          1A  H
A            DDTEXT        24A  O  1  5
A            DDVALUE        2A  H
A          R SBFDDCTL                  SFLCTL(SBFDD)
A                                      SFLSIZ(2)
A                                      SFLPAG(1)
A N99                                  SFLDSP
A N99                                  SFLDSPCTL
A  99                                  SFLCLR
A                                      OVERLAY

Figure 1e. How to save the DDS source when exporting a Mobile RPG display file to the IBM i

How to load the DDSList subfile for dropdown use

Before the record format containing the DDSList dropdown is displayed, it needs to be populated with dropdown data. The code below in Figure 2a shows a way to do this.

Declare a data structure for each dropdown item and a corresponding data array of this data structure. This data structure defines the data elements used to provide a given dropdown element’s text and value. States is an array of StateInfo. This array is the source data for the DDSList’s subfile.

Dcl-DS StateInfo Qualified;
	State Char(48);
	Abbrev Char(2);
End-DS;

Dcl-DS States LikeDS(StateInfo) Dim(100);

Figure 2a. Declaring a data structure and a data structure array for dropdown data.

A data structure array provides good interim storage for any of Mobile RPG’s controls that use a subfile. Using a data structure for list elements does two important things:

• It enables separating the task of populating the DDSList subfile from the task of fetching that data (which usually means reading it from a data file). This makes it easy to have one routine that populates the array with test data and another that populates it with production data.

• The data structure array can be passed to other RPG programming to populate it, letting you further separate specific data handling concerns.

The StateInfo structure uses field lengths dictated by the field lengths in the file that will ultimately be read to populate the States array.

The LoadStatesList procedure below in Figure 2b isn’t concerned with how the States array is populated–rather, its job is to use the States array to load the DDSList’s subfile.

Dcl-Proc LoadStatesList;
    Dcl-Pi *N;
    End-Pi;            

    Dcl-S RowsReturned Int(10);
    Dcl-S Index Int(10);

    RowsReturned = GetStates();

    *IN99 = *On;
    Write SBFDDCTL;
    SbfRRN = 0;

    For Index = 1 To RowsReturned;
        DDText = States(Index).State;
        DDValue = States(Index).Abbrev;
        DDSel = '0';
        SbfRRN = SbfRRN + 1;
        Write SbfDD;
    EndFor;

    *In99 = *Off;
    Write SBFDDCTL;
End-Proc;

Figure 2b. Populating the DDSList’s subfile with the States data structure array.

In the LoadStatesList procedure above, GetStates returns the number of active elements in the States array. The For loop uses this value to know how many rows to write to the subfile.

The GetStates procedure loads the States array for test purposes with five, hardcoded states. In a production app you’d change GetStates to read the data from a data file. In this case, the procedure’s return value (the number of elements written to the States array is hardcoded. In a production routine to fetch the states list from a data file, the return value would be dynamically determined from the number of rows read to populate the list.

Dcl-Proc GetStates;
    Dcl-Pi *N Int(10);
    End-Pi;            

    Dcl-S Index Int(10);
    
    Index = 1;
    States(Index).State = 'Alabama';
    States(Index).Abbrev = 'AL';    

    Index = 2;
    States(Index).State = 'Colorado';
    States(Index).Abbrev = 'CO';    

    Index = 3;
    States(Index).State = 'Illinois';
    States(Index).Abbrev = 'IL';    

    Index = 4;
    States(Index).State = 'Georgia';
    States(Index).Abbrev = 'NV';    

    Index = 5;
    States(Index).State = 'Nevada';
    States(Index).Abbrev = 'NV';    

    Return 5;
End-Proc;         

Figure 2c. Populating the data structure array with hard-coded data.

An upcoming article will discuss how to create an SQL-driven GetStates ILE RPG procedure that fetches the state list
from a data file.

Summary

As you can see, it’s not hard to use the DDSList to provide a dropdown control for your Mobile RPG apps. If you’re using the DDSList for this purpose, please send us a screenshot, we’d love to see!