Support This Project Get i5/OS Programmer's Toolkit at Fast, secure and Free Open Source software downloads

ILE RPG Header for User Interface Manager (UIM) APIs

Go back to main page of project i5/OS Programmer's Toolkit .

ILE RPG Header for User Interface Manager (UIM) APIs ( uim.rpgleinc ) is a subproject of i5/OS Programmer's Toolkit . It was designed to simplify RPG programmers' works when working with the UIM. uim.rpgleinc provides prototypes of UIM APIs and declarations of parameter structures used by UIM exit programs. For detail documentation of UIM APIs and parameter structures of UIM exit programs, please refer to the Information Center:


Overview of User Interface Manager (UIM)

The i5/OS User Interface Manager (UIM) is a part of the system that allows you to define panels and dialogs for your application and provides the following support:

The UIM controls the panel’s appearance and assures consistency with panels developed by IBM. This gives an application a consistent user interface which increases user productivity. Application programmer productivity is increased by using the UIM to create panels. The application programmer can describe the contents of a panel without specifying all the details. The format of the panel’s elements is handled automatically by the UIM.

In contrast with DDS UIM has the following advantages:

How to Get uim.rpgleinc

To get the ILE RPG Header for UIM APIs, uim.rpgleinc, you may download and install the last release package of project i5/OS Programmer's Toolkit by visiting the following link: . You may also check it out from the project's SVN repository seperately like the following:
svn export

After exporting the source stream file of uim.rpgleinc, you can upload it to your i5/OS machine either as a stream file in the IFS or as a source PF member by FTP. Make sure that uim.rpgleinc can be seen by the RPG compiler by setting a proper value to the INCDIR parameter of CRTBNDRPG or CRTRPGMOD when you compiling a RPG source unit that includes uim.rpgleinc.

Getting Started with ILE RPG Header for UIM APIs

Here are several "hello world!" examples. If you are new to the UIM or uim.rpgleinc, we hope that these examples would be helpful.

Define a Simple Menu Panel

The following image shows a simple menu panel through which users can select CL commands to run by typing a menu number at the "Selection" position and hit the enter key.

UIM describes UI elements and interactive characters using a tag-based language, the UIM panel group definition language. Sources written in this tag-based language can then be compiled into panel group objects (*PNLGRP) or menu objects (*MENU) by using CL command Create Panel Group (CRTPNLGRP) or Create Menu (CRTMNU). To start an interactive UIM application, you should invoke the Open Display Application (QUIOPNDA) API with a valid *PNLGRP name. The QUIOPNDA API returns a unique 8-byte handle value which should be used in all the following operations with the current UIM application. For example, opening a panel defined in the panel group object, or closing the UIM application.

The complete source of the above-showed panel group object is available at: t075.uim . Now let's go through some of the key points in it.


:copyr.Copyright text ... &colon.p

.* classes
:class  name=clspgm
        basetype='char 20'
:class  name=o50
        basetype='igc 50'.

.* variables
:var    name=vpgmf5
:var    name=vtitle

.* records
:varrcd name=rcdttl
:varrcd name=rcdpgm

.* key lists
:keyl   name=klistmain.
.* ... ...
:keyi   key=f5
        action='call vpgmf5'
.* ... ...

.* main panel
:panel  name=mainpanel

:menu depth='*'
:topinst.Select one of the following
:menui option=1
       action='CMD DSPLIBL'
       .Display Library List
.* ... ...



.* help definitions
:help   name='help/help'.T075 - help
'i cannot help you :('


Syntax of UIM Tags
A UIM tag always starts with a colon character `:' and ends with a dot character `.'. A tag name string must occurs closely after the colon. Zero or more attributes in form of 'ATTR=value' may occur after the tag name according to the syntax of each kind of tag. Single quote characters `'' must be used to enclose attribute values that contains characters other A through Z or 0 through 9. One 'ATTR=value' pair must remain in one line. All characters between the colon `:' and dot `.' characters will be converted uppercase during the compile process. Text strings can appear after the dot character for some of the UIM tags such as :help. (help tag) and :copyr. (copyright tag). Some UIM tags, such as tags that can contain other tags, needed to be end by another tag named 'ETAGNAME'. For example, the PNLGRP tag need to be ended with a EPNLGRP tag. The order that different type of UIM tags occur in a source file are important.

The Panel Group Tag (PNLGRP)
The panel group (PNLGRP) tag begins the definition of a panel group. Only one PNLGRP tag is allowed and a matching EPNLGRP tag is required. All other tags must be nested in the PNLGRP tag. The following

CLASS tags are used to define data types in UIM. In t075.uim, two data types are defined:

A CLASS tag must be ended with a corresponding ECLASS tag.
The VAR Tag and the VARRCD Tag
The VAR (variable) tag and the VARRCD (variable record) tag are used to represent a single variable or a record of variables respectively. UIM APIs that get or set UIM variables work basing on VARRCDs.

The KEYL Tag and the KEYI Tag
The KEYL tag is used represent function key lists in UIM. The KEYI tag is used to define a key item in a KEYL tag. The action attribute of a KEYI tag defines the action occurring when the function key is pressed. In the above example, the ACTION attribute function key F5 is defined to 'call vpgmf5'. Here 'call' is a UIM dialog command that invoke an exit program identified by a UIM variable.

A KEYL tag must be ended with a corresponding EKEYL tag.
In UIM we use the PANEL tag to define one or more panels in a panel group object. In this example, the following attributes are set for the only PANEL tag in *PNLGRP T075:

The MENU Tag and the MENUI Tag
The MENU tag and the MENUI tag are used to represent menus and mene items in UIM. In the above example, the menu item whose option number is one is defined to invoke CL command DSPLIBL.

Start a UIM Application and Display a Panel Defined in a Panel Group Object

ILE RPG program t075.rpgle is supposed to open a UIM display application and display the above metioned menu panel. The following is the complete list of ILE RPG program t075.rpgle .

     h dftactgrp(*no) dftname(T075)

     /* include ILE RPG header for UIM APIs, uim.rpgleinc [1] */
      /include uim

     d i_main          pr                  extpgm('T075')
     d     uim_parm                        likeds(qui_common_t)

     d apph            s              8a
     d pnlgrp          s             20a   inz('T075      *LIBL')
     d scope           s             10i 0 inz(-1)
     d exitpgm_int     s             10i 0 inz(0)
     d full_screen_help...
     d                 s              1a   inz('Y')
     d ec              ds                  likeds(qusec_t)
     d                                     based(ecptr)
     d ecptr           s               *
     d eclen           c                   64
     d rtn             s             10i 0
     d panel           s             10a   inz('MAINPANEL')
     d redisp_opt      s              1a   inz('N')
     d close_opt       s              1a   inz('M')
     d rcd_name        s             10a   inz('RCDTTL')
     d rcd_title       ds                  qualified
     d     panel_title...
     d                               50a
     d rcd_extpgm      ds                  qualified
     d     pgm                       20a
     d     pgm_name                  10a   overlay(pgm:1)
      * buffer length
     d buflen          s             10i 0
      * who am i?
     d who_am_i        pr            20a

     d i_main          pi
     d     uim_parm                        likeds(qui_common_t)
     d     uvv         ds                  likeds(qui_common_t)

           ecptr = %alloc(eclen);
           ec.bytes_in = eclen;

           // open UIM display application [2]
           quiopnda( apph : pnlgrp : scope : exitpgm_int
                   : full_screen_help : ec);

           if ec.bytes_out <> 0;
               // error handling

           // set panel title [3]
           rcd_title.panel_title = 'Hello UIM :p';
           buflen = %size(rcd_title);
           quiputv( apph : rcd_title : buflen : rcd_name : ec);

           // set T077 as the exit pgm of function key F5 [4]
           rcd_extpgm.pgm = who_am_i();
           rcd_extpgm.pgm_name = 'T077';
           buflen = %size(rcd_extpgm);
           rcd_name = 'RCDPGM';
           quiputv( apph : rcd_extpgm : buflen : rcd_name : ec);

           // display main panel [5]
           quidspp( apph : rtn : panel : redisp_opt : ec);

           // close UIM display application [6]
           quicloa( apph : close_opt : ec);

           dealloc ecptr;
           *inlr = *on;

      * Subprocedure who_am_i() is designed to return the program name
      * and library name of the program currently being
      * invocated. [7]
     p who_am_i        b
      /copy mih52

     d me              ds                  likeds(matpgmnm_tmpl_t)
     d pgm             ds            20    qualified
     d   obj                         10a
     d   lib                         10a

     d                 pi            20a

           propb(%addr(me) : x'00' : matpgmnm_tmpl_len);
           me.bytes_in = matpgmnm_tmpl_len;
           me.format   = 0;

           pgm.obj = me.bpgm_name;
           pgm.lib = me.ctx_name;

           return pgm;
     p who_am_i        e

Key points in the above ILE RPG program:

Handling Input Requests in UIM Exit Programs

To handle input requests from interactive users, UIM defines a set of exit program interfaces. By setting the Exit parameter interface parameter of QUIOPNDA or QUIOPNPA to 0, you can indicate the UIM to pass exit program parameters as a single space pointer to a data structure that contains all the exit program parameters. This is the most efficient way to exchange parameters between the UIM and exit programs. uim.rpgleinc is supposed to involve all the parameter structures of UIM exit programs. In the following we will added an exit program for the above example to handle function key F5, t077.rpgle .

      /copy apiec
      /copy uim
     d i_main          pr                  extpgm('T077')
     d     uim_parm                        likeds(qui_fkc_t)

     d rcd_title       ds                  qualified
     d     panel_title...
     d                               50a
     d rcd_name        s             10a
     d ec              ds                  likeds(qusec_t)
     d                                     based(ecptr)
     d ecptr           s               *
     d eclen           c                   64
     d buflen          s             10i 0

     d i_main          pi
     d     uim_parm                        likeds(qui_fkc_t)

           if uim_parm.basic.call_type <> 1; // processes a function key
               *inlr = *on;

           ecptr = %alloc(eclen);
           ec.bytes_in = eclen;

           when uim_parm.func_key = 5; // F5
               rcd_title.panel_title = 'Hello UIM ' +
               rcd_name = 'RCDTTL';
               buflen = %size(rcd_title);
               quiputv( uim_parm.basic.apph
                      : rcd_title
                      : buflen
                      : rcd_name
                      : ec);

           dealloc ecptr;
           *inlr = *on;

Note that structure qui_fkc_t defines the parameters passed by the UIM to an exit program when a function key is pressed. After the user pressed F5 in the above menu panel, the title of the panel might changed to somewhat like the following.


Example List

List of examples that utilize prototypes of UIM APIs and UIM exit program parameter structures.

Example Sources Description

t075.uim , t075.rpgle , t077.rpgle . In this example, a simple menu panel is displayed by RPG progam t075.rpgle. RPG program t077.rpgle acts as the function key handling exit program.

Support This Project
Generated on Mon Oct 3 04:10:44 2011 for i5/OS Programmer's Toolkit: System-builtin Headers for ILE RPG by  doxygen 1.5.9