|
|
|
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:
Topics
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:
svn export https://i5toolkit.svn.sourceforge.net/svnroot/i5toolkit/rpg/uim.rpgleinc
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.
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.
:pnlgrp. :copyr.Copyright text ... &colon.p .* classes :class name=clspgm basetype='char 20' . :eclass. :class name=o50 basetype='igc 50'. :eclass. .* variables :var name=vpgmf5 class=clspgm . :var name=vtitle class=o50 . .* records :varrcd name=rcdttl vars='vtitle' . :varrcd name=rcdpgm vars='vpgmf5' . .* key lists :keyl name=klistmain. .* ... ... :keyi key=f5 help='help/help' action='call vpgmf5' .F5=Refresh .* ... ... :ekeyl. .* main panel :panel name=mainpanel title=vtitle help='help/help' keyl=klistmain . :menu depth='*' scroll=no botsep=space. :topinst.Select one of the following :menui option=1 action='CMD DSPLIBL' help='help/help' .Display Library List .* ... ... :emenu. :optline.Selection :epanel. .* help definitions :help name='help/help'.T075 - help :p. 'i cannot help you :(' :ehelp. :epnlgrp.
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
The CLASS Tag
CLASS tags are used to define data types in UIM. In t075.uim, two data types are defined:
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.
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.
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)
/free
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
endif;
// 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;
/end-free
/*
* 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
/free
propb(%addr(me) : x'00' : matpgmnm_tmpl_len);
me.bytes_in = matpgmnm_tmpl_len;
me.format = 0;
matpgmnm(me);
pgm.obj = me.bpgm_name;
pgm.lib = me.ctx_name;
return pgm;
/end-free
p who_am_i e
Key points in the above ILE RPG program:
/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)
/free
if uim_parm.basic.call_type <> 1; // processes a function key
*inlr = *on;
return;
endif;
ecptr = %alloc(eclen);
ec.bytes_in = eclen;
select;
when uim_parm.func_key = 5; // F5
rcd_title.panel_title = 'Hello UIM ' +
%char(%timestamp());
rcd_name = 'RCDTTL';
buflen = %size(rcd_title);
quiputv( uim_parm.basic.apph
: rcd_title
: buflen
: rcd_name
: ec);
other;
endsl;
dealloc ecptr;
*inlr = *on;
/end-free
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 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.
|
Generated on Mon Oct 3 04:10:44 2011 for i5/OS Programmer's Toolkit: System-builtin Headers for ILE RPG by
1.5.9