ASNA Mobile RPG (MR) enables RPG programmers to create very effective IBM i mobile smartphone applications with ILE RPG. MR includes many user interface controls. For example, with MR you can easily:

  • Render an interactive Google map
  • Show a drill-down data chart control (with bar and pie charts)
  • Provide buttons, labels and read/write input fields
  • Determine the user's current GEO location
  • Read barcodes with phone camera
  • Upload pictures taken with a phone camera
  • Display images
  • Show data in lists with one or more columns
  • Upload and download binary files (such as PDFs) to the IBM i IFS
  • Capture a user's signature and save it as a JPG file to the IBM i IFS

These controls are all driven by setting property values that govern their behavior. This article takes a look at the signature capture control (DdsSignature) and shows how it works. A single-panel MR app accompanies this article and is available for download. Its initial UI is shown below in Figure 1.

Figure 1. An MR panel that captures a user's signature

It includes six primary controls:

  1. A button to end using the program
  2. An output-only field to show the customer name
  3. An output-only field to show the job ticket number
  4. The MR signature capture control
  5. An input/output field for the signee's last name (often used to establish signature validity when sloppy signatures are provided)
  6. A button to accept the signature

The properties for each of these controls is shown below:

#1 The exit button (DdsButton)

Property Value Description
AidKey 'F3' Exit the app

The AidKey F3 is associated with indicator 03 as its response indicator.

Tapping this button is seen by the RPG program as the user having pressed the F3 function key.

#2 The signee's full name (DdsCharField)

Property Value Description
Alias 'FullName' Signee full name
Length 60 Length of 'FullName' field

This value is presented as a 60-character field named FullName to the RPG program.

#3 The job ticket number (DdsButton)

Property Value Description
Alias 'JobTick' Signee full name
Length 12 Length of 'JobTick' field

This 12-character value displays a field from the RPG program named JobTick.

#4 The signature capture control (DdsSignature)

Property Value Description
DirectoryField 'IfsDir' Name of target IFS directory
DirectoryFieldLength 128 Length of DirectoryField
NameField 'IfsFilNam' Image file name
NameFieldLength 40 Length of NameField

The DdsSignature control does all of the work related to capturing an image and storing it on the IBM i. It has two "modes". The mode shown initially is output only. When its "Tap here to sign" link is clicked, it becomes input capable (we'll discuss this in more detail in a moment). The signature capture uses the four properties shown above to track the signature image's IFS directory and file name. In this case, the field specified by the DirectoryField property is 128 characters long and the field specified by the NameField is 40 characters long. The directory specified by the DirectoryField must exist.

#5 The signee last name (DdsCharField)

Property Value Description
Alias 'SigLName' Signee full name
Length 50 Length of 'SigLName' field

This 12-character value displays a field from the RPG program named SigLName.

#6 The accept button (DdsButton)

Property Value Description
AidKey 'F6' Accept the signature

The AidKey F6 is associated with indicator 06 as its response indicator.

Tapping this button is seen by the RPG program as the user having pressed the F6 function key. Pressing this button submits the app's form and causes the captured image to be stored on the IBM i in the specified IFS directory with the file name provided.

Capturing the signature

To start the signature capture, the user taps the "Tap here to sign" link on the screen shown in Figure 1. This causes the display shown below in Figure 2 to be displayed:

Figure 2. Ready for signature capture

There are four possible use actions on this panel, all of which are controlled by the signature capture control:

  1. Sign with a fingertip on the dashed line
  2. Tap "Done" when the signature has been provided
  3. Tap "Cancel" to cancel providing a signature
  4. Tap "Clear and sign again" to redo the signature

Clicking "Done," "Cancel," or "Clear," all return to the previous screen (the screen shown in Figure 1.)

After signing, the signature is available in the app but hasn't yet been sent to the IBM i. Upon providing the signature and tapping "Done," the screen below in Figure 3 is shown.

Figure 3. Tapping "Accept" sends the signature to the IBM i in a JPG to the IFS

This panel is the same as the one shown in Figure 1, but now it has a signature loaded. After the user's last name is entered, tapping "Accept" sends the screen's data (which in this case is the signature and the signee's last name) to the IBM i. The signature itself doesn't need any RPG, the control does all the work to store the image in the IFS. The signee's last name is present in the RPG program where you could write it to a file.

In the example app, after tapping the "Accept" button the RPG redisplays an empty signature capture panel again. In production applications, the RPG program would most likely display a different panel.

How does this all work?

Without having used Mobile RPG the notion of nothing but good ol' ILE populating a mobile UI on a smartphone surely seems like black magic. It's not and it's not that hard to understand. Let's see how MR RPG works.

  1. Start a new Mobile RPG project in Microsoft Visual Studio. Don't worry, you aren't going to write any code in Visual Studio, the logic and database access all happens in an ILE RPG program. Mobile RPG scaffolds a "Hello, world" app for you with a basic display file and RPG program ready to run.

  2. Create the UI. Using Visual Studio, you drag and drop controls as needed on the app's form. You can also add as many record formats, each with its own set of controls, as necessary. For each control, you set the necessary properties. (Read more about Mobile RPG's UI controls here.)

  3. Export the Mobile RPG UI to the IBM i as a traditional display file. This display file will not be seen by human eyeballs. Its purpose is to have an IBM i representation of the mobile UI with which to compile the RPG program. For example, consider the screen shown in Figure 1. Exporting it produces a traditional display file as defined below:

      A                                      DSPSIZ(27 132 *DS4) 
      A                                      INDARA              
      A          R SIGCAP                                      
      A                                      OVERLAY             
      A            FULLNAME      60A  O  1  2                    
      A            JOBTICK       12A  O  1 64                    
      A            IFSDIR       128A  H                          
      A            IFSFILNAM     40A  H                          
      A            SIGLNAME      50A  B  3 43                    
    

    This article doesn't show it directly, but there is a record format named SigCap. You can see how the fields defined on the screen in Figure 1 (via control properties) translate directly to this traditional display file. The underlying RPG for the mobile app uses this display file for compile-purposes.

  4. Write the RPG program. The ILE RPG for this signature capture program is shown below.

    Mobile RPG doesn't care how you write the ILE RPG. Here is a fixed-format version:

     FSIGCAPDSPFCF   E             WORKSTN Handler('MOBILERPG')             
    
     C********************************************************************* 
     C* Use the RPG cycle to display the HomeMenu format.
     C* End the program on IN03         
     C********************************************************************* 
     C* Hard-coded name and job ticket values.
     C                   Eval      FullName = 'Bernard Shakey'              
     C                   Eval      JobTick = '5386'                         
     C                   Eval      IFSDir = '/home/SHAKEY/signatures'       
     C                   Eval      IFSFilNam = JobTick + '.jpg'             
     C                   ExFmt     SIGCAP                                 
     C                   Select                                             
     C                   When      *In03                                    
      * End the program.
     C                   Eval      *InLR = *On                              
     C                   When      *IN06
      * Do something here to persist the 'SigLName' field 
      * and display a different format.
     C                   Return                                             
     C                   EndSl
    

    And here is a free format version (which we vastly prefer at ASNA but you pick!):

     Ctl-Opt Option(*srcstmt) Dftactgrp(*No) ActGrp('rpmobile');        
    
     Dcl-F HelloDspf WORKSTN Handler('MOBILERPG');                                                                                    
     // Use the RPG cycle to display the HomeMenu format.
     // End the program on IN03         
    
     // Hard-coded name and job ticket values.
     FullName = 'Bernard Shakey'              
     JobTick = '5386'
    
     IFSDir = '/home/SHAKEY/signatures'       
     IFSFilNam = JobTick + '.jpg'             
    
     ExFmt SIGCAP;                                                    
    
     Select;                                                            
         When *In03;
             // End the program.
             *InLR = *On;                                               
             Return;      
    
         When *In06;
              // Do something here to persist the 'SigLName' field 
              // and display a different format.
     EndSl;
    

    For this example, the FullName, JobTick, IFSDir, and IFSFilNam fields are hardcoded. In a production app these values would most likely have been read from disk files.

    *IN03 is on when the user taps the exit button. *IN03-governed logic ends the program by setting on *InLR and doing a return.

    *IN06 is on when the user taps the Accept button. In this example no code is neccesary in the *IN06-governed logic. But in a production app, this is where you'd cause the mobile app to display a difference record format.

    Except for providing the IFS DirectoryField and NameField values, there is no other RPG (or any other code for that matter) required for the signature capture control to do its work.

    You can use the IBM i WRKLNK command to see the captured signatures.

    With the image in the IFS, you can insert it in traditional print file as shown below:

    Here is an example of the Printer File DDS used in printing a signature capture via DdsSignature as a JPG.

     A        R SIGNREC1
     A                              BOX(5 5 6 8.5 0.02    + 
     A                              (*COLOR *RGB 20 15 75)) 
     A                              AFPRSC('mysig1.jpg'   + 
     A                              *JFIF 5 5             + 
     A                              (*SIZE 3.5 1.0)       + 
     A                              (*MAPOPT *ST)         + 
     A                              (*PATH '/home/SHAKEY/signatures'))
    

    You can also display it in a Mobile RPG display file using the DdsImage control.