APIs by Example: UIM & Work Management APIs, Part 1

Article ID: 52665

Posted June 8th, 2006

By:

The Work Management APIs, User Interface Manager (UIM) APIs, and UIM List Panels are a strong combination if you want to extend or specialize the functions, screens, and reports that the native i5/OS work management commands offer. The Work with Subsystem Activity (WRKSBSACT) command that I include in today's installment of APIs by Example demonstrates how this can be done and also offers an interface to a couple of other new work management commands, which I will present in upcoming installments of APIs by Example.

Today I explain the different components of a UIM List Panel Group and the UIM tag language, which is used to define and create a panel group object. But first, let me show you the command prompt of the WRKSBSACT command:

            Work with Subsystem Activity (WRKSBSACT)                   
Type choices, press Enter.                                                    
Subsystem  . . . . . . .   *ACTIVE   Name, generic*, *ACTIVE, *ALL
  Library  . . . . . . .             Name, *LIBL, *CURLIB...      
Exclude subsystem lib  .   *NONE     Name, generic*, *NONE

You can enter either a specific name, a generic name, or *ALL for subsystem name and, combined with the possible library name values, you can display many different subsets of the subsystems on your system. The single value *ACTIVE simply displays all currently active subsystems.

The Exclude subsystem library parameter is useful if you want to avoid the many duplicate IBM subsystems that you find in system libraries, such as QINMEDIA, QINPRIOR, and QINSYS. To exclude these libraries, specify EXCLUDE(QIN*) on the WRKSBSACT command.

Here's a sample display of the Work with Subsystem Activity list panel resulting from running the command WRKSBSACT SBS(Q*):


                  Work with Subsystem Activity           WYNDHAMW 
                                               25-05-06  15:11:09 
Type options, press Enter.                                                     
  2=Change   4=Delete   5=Display      8=Work with subsystem jobs          
  9=Start subsystem     10=End subsystem
  12=Work with subsystem job queues   
Opt  Subsystem   Library     Status      Max jobs  Current active            
     QBASE       QSYS        *INACTIVE     *NOMAX            0               
     QBATCH      QSYS        *INACTIVE     *NOMAX            0               
     QCMN        QSYS        *ACTIVE       *NOMAX            7               
     QCTL        QSYS        *ACTIVE       *NOMAX            2               
     QDSNX       QGPL        *INACTIVE     *NOMAX            0               
     QFNC        QGPL        *INACTIVE     *NOMAX            0               
     QINTER      QSYS        *INACTIVE     *NOMAX            0               
     QLPINSTALL  QSYS        *INACTIVE     *NOMAX            0               
     QMQM        QMQM        *ACTIVE       *NOMAX           29               
     QPGMR       QSYS        *INACTIVE     *NOMAX            0
     QSERVER     QSYS        *ACTIVE       *NOMAX           42                   
                                                          More... 
Parameters or command                                                          
===>                                                                           
F3=Exit  F4=Prompt  F5=Refresh   F6=Create subsystem  F9=Retrieve           
F11=Display text    F12=Cancel   F21=Print list

Most of the available options are well known from either the Work with Subsystems (WRKSBS) or the Work with Subsystem Description (WRKSBSD) commands, but option 12 takes you to the new Work with Subsystem Job Queues (WRKSBSJOBQ) command, which I will include in the next APIs by Example. Online, cursor-sensitive help provides detailed explanation of all available options, function keys, and list panel fields.

As in the previous API by Example (see references and links at the end of this article), the CPP of the WRKSBSACT command mainly takes care of the retrieval of the information presented in either the header or the list part of the display and print panel. When the information is retrieved and loaded into the variable pool of the list panel group, the UIM performs the list presentation and screen dialog.

Last time, I explained some of the basic UIM panel group concepts, namely Application Handle, UIM Exit Programs, and Variable Pool. To further expand on the topic, let me continue with the actual UIM tags as they are coded in the CBX156P panel group source. Here's the required order of UIM tags in a panel group source, as well as a short description of each. Please note that the indented tags are valid only in the context in which they appear. An (O) following the tag description indicates that the tag is optional.

:PNLGRP  - Panel group  Defines the beginning of a panel group.

:COPYR   - Copyright    Presents a copyright notice in the message
                        area of the first panel displayed. (O)
:IMPORT  - Import       Makes help modules in other panel groups
                        available in the current panel group. This
                        makes keeping all help modules in one panel
                        group possible, as in this example. (O)

:CLASS   - Data class   Defines the variable types of the fields
                        in the variable pool. Value translation
                        and value checks are defined as part of
                        the class definition.
           :TL          Translation list. Performs translation
                        between internal and external values, for
                        example -1 is displayed as *NOMAX (and
                        vice versa).
           :CHECK       Validity checking. Specifies a range, a list
                        of values, or a relational condition to
                        check the variable value against.   

:VAR     - Variable     Declares a dialog variable in the panel
                        group. The variable's data type (including
                        value translation and check) is defined by
                        the assigned class name.

:VARRCD  - Record       The variable record or structure used to
                        pass data between application and variable
                        pool. Defines the variables included in the
                        specified record and the sequence in which
                        they must appear.

:LISTDEF - List         Defines the lists or data structures that
                        UIM uses to build the actual panel lists
                        displayed or printed. A list entry is based
                        on the data in the variable record.

:COND    - Condition    Specifies a certain condition that can be
                        used to control the appearance and 
                        behavior of the panel group -- for example,
                        if a specific function key should be
                        displayed and allowed. (O)

:TT      - Truth table  Used by the compiler to define how many
                        different sets of conditions can be true
                        at any given time. An individual panel
                        format is generated for each set. (O)

           :TTROW       Truth table row. Specifies a set of truth
                        table rows to define mutually exclusive
                        conditions to the compiler.

:KEYL    - Key list     Defines sets of available function keys
                        and the function they perform. A key list
                        is eventually assigned to each panel
                        definition.

           :KEYI        Key list item. Defines a single function
                        key and the action that it should perform.
                        A number of UIM predefined actions are
                        available -- for example, CHGVIEW, CANCEL,
                        CMD, and CALL. 

:PANEL   - Panel        The panel tag defines the beginning of a
                        display panel format and many other panel
                        related attributes -- for example, panel
                        name, user exit program, panel dialog
                        variables, and much more.

           :DATA        Data presentation area. Describes a data
                        presentation area in a panel. In a list
                        panel, this tag is used to describe the
                        format heading the list, if there is any.
                        The DATA tag is also used to define non-
                        list panels. (O)

           :LIST        List area. Defines the list area of the
                        panel, including separator attributes,
                        view dialog variable, parms dialog
                        variable, and of course the list definition
                        (LISTDEF) that the current list is
                        defined by.

             :TOPINST   Top instruction. Text that appears in the
                        top section of the list.

             :LISTACT   List action. Defines the options available
                        to perform against the list entries.
             :LISTGRP   List column group. Specifies a list of
                        list columns that are related and should
                        appear in the list as such.
             :LISTCOL   List column. Specifies each list column
                        and a number of attributes related to it.

             :LISTVIEW  List view. Defines the different list
                        views, meaning the actual constellation of
                        list columns and list groups, and the
                        order in which they appear. More than one
                        view can be defined, using the CHGVIEW
                        dialog command to toggle between them.   
           :CMDLINE     Command line. Defines a command-line area
                        in which commands and list action parameters
                        are entered. (O)
:PRTHEAD - Print head   Contains the tags defining the header 
           panel        section of a printed list as well as a
                        number of related attributes.

           :PRTTRAIL    Print trailer message. Specifies a message
                        to indicate the end of the printed list.
                        (O) 

:PRTPNL  - Print panel  Defines one or more area definitions for a
                        print panel:

           :DATA        Data presentation area. Describes a data
                        presentation area in a panel. In a list
                        panel, this tag is used to describe the
                        format heading the list. (O)

           :LIST        List area. Defines the list area of the
                        panel, including separator attributes
                        and the list definition (LISTDEF) that the
                        current list is defined by. Most of
                        the tags defined for the LIST tag in the
                        PANEL context tag also apply in the
                        PRTPNL context.

This list is by no means exhaustive in terms of UIM tags available or their description, but it gives you a brief overview of the tags used in this and following UIM list panel group examples.

For the full list of UIM tags and a detailed explanation of each, refer to the Application Display Programming manual, Appendix A. A link is provided at the end of this article. For an explanation of UIM objects and functions, Chapter 17 is also a great source of information and provides detailed descriptions of UIM concepts and characteristics.

For more information about the concepts and components of UIM list panel groups, also refer to Ozubike Oguine's article, "Creating a UIM List Application" (a link is provided at the end of this article).

I will continue my investigation and explanation of UIM list panel groups next time around. And I as I mentioned at the beginning of this article, I will also add the WRKSBSJOBQ command to my suite of new work management commands.

This APIs by Example includes the following sources:

CBX156  -- Work with Subsystem Activity - CCP               
CBX156E -- Work with Subsystem Activity - UIM Exit Program  
CBX156H -- Work with Subsystem Activity - Help              
CBX156P -- Work with Subsystem Activity - Panel Group       
CBX156V -- Work with Subsystem Activity - VCP               
CBX156X -- Work with Subsystem Activity                     

CBX156M -- Work with Subsystem Activity - Build command

To create all these objects, compile and run CBX156M. Compilation instructions are in the source headers, as usual.

Creating a UIM List Application, by Azubike Oguine:
http://www.iseriesnetwork.com/article.cfm?id=1732

Previously published UIM-related APIs by Example articles:
http://www.iseriesnetwork.com/article.cfm?id=52457
http://www.iseriesnetwork.com/article.cfm?id=52574

UIM APIs — printable PDF:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis_web/uim.pdf

Application Display Programming (see pages 271-660) — printable PDF:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/books/sc415715.pdf

This article demonstrates the following APIs:

Retrieve Subsystem Information (QWDRSBSD) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwdrsbsd.htm

Open List of Objects (QGYOLOBJ) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgyolobj.htm

Get List Entries (QGYGTLE) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgygtle.htm

Close List (QGYCLST) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qgyclst.htm

Open Display Application (QUIOPNDA) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quiopnda.htm

Close Application (QUICLOA) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/quicloa.htm