APIs by Example: User Application Information APIs, Part 3

Article ID: 52457

Posted April 27th, 2006

By:

This APIs by Example delivers the final installment of the User Application Information APIs article series. Here, I show you how user application information can be put to practical use. This article also ties a thread back to another previously published article demonstrating recent enhancements to API date and time zone support. Links to all these articles are provided at the end of this article. Further, today's issue delivers a brand-new Work with User Time Zone Information (WRKUSRTMZ) command, which also constitutes a first in this column, as far as UIM List Panel Groups and User Interface Manager (UIM) APIs are concerned.

Though most of these APIs have been around since V2R2, I rarely encounter applications or utilities that take advantage of UIM panel groups and APIs. One very interesting exception to that rule is Azubike Oguine, who wrote a number of articles demonstrating UIM API and panel group coding techniques that were published in iSeries NEWS. I recommend using Azubike's articles as a guide and inspiration if you run into obstacles while developing your own UIM utilities. Some of them explain in great detail the many different UIM concepts, conventions, and structures. At the end of this article, I provide a link to Azubike's articles.

In part two of this series, I explained the layout of the User Time Zone Information structure and the APIs available to manage the User Application Information. Now it's time to actually use this information. To provide an example of how this can be done, I created the WRKUSRTMZ command. This command offers an easy access to manage user time zone information and provides an opportunity to display the effect of setting a user profile's time zone information. Here's the command's prompt:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

             Work with User Time Zone Info (WRKUSRTMZ)      
Type choices, press Enter.                                        
User profile . . . . . . . .                 Name, generic*   

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

You can select either a single user profile to work with or, by specifying a generic user profile name, a list of user profiles. Similar to the other User Time Zone Information commands, the WRKUSRTMZ command requires *ALLOBJ and *SECADM special authority to run.

The *ALLOBJ requirement can be relaxed if you choose to do so, but *READ authority to the user profile is still required in order to change its user application information.

After you create the WRKUSRTMZ command, it is immediately available on the CMDUSRTMZ menu that was part of the previous article:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

CMDUSRTMZ        User Time Zone Information Commands                       
                                               System:   WYNDHAMW 
Select one of the following:                                                   
  Commands                                                                     
     1. Add User Time Zone Information                  ADDUSRTMZ  
     2. Change User Time Zone Information               CHGUSRTMZ  
     3. Remove User Time Zone Information               RMVUSRTMZ  
     5. Work with User Time Zone Information            WRKUSRTMZ
  Related Command Menus                                                        
    10. Time Zone Description Commands                  CMDTIMZON  
                                                                        Bottom 
Selection or command                                                           
===>                                                                           
F3=Exit   F4=Prompt   F9=Retrieve   F12=Cancel                                 

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

If you added time zone information for one or more user profiles following the installation of the other User Time Zone Information commands, I suggest that you run the WRKUSRTMZ command against these user profiles. For example, if one or more of those profiles begins with the letter 'C', run the command:

  WRKUSRTMZ USRPRF(C*)

This should take you to the following display:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                 Work with User Time Zone Information             WYNDHAMW
                                           22-04-06  15:53:02 CET
Type options, press Enter.                                                    
  2=Change time zone information   4=Remove time zone information             
        User                          Time zone      Display                  
Opt     Profile        Time zone      Abbr           Time zone                
        CHUCK          QP0100CET3     CET              *YES                   
                                                                        Bottom
Parameters or command                                                         
===>                                                                          
F3=Exit  F4=Prompt  F5=Refresh  F6=Add  F9=Retrieve  F12=Cancel          

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

If you get an empty panel, use F6 to add time zone information to a user profile of your choice. Cursor-sensitive help text is provided for both the command and the list panel group. As you've probably guessed, option 2, option 4, and function key F6 activate the Change, Remove, and Add User Time Zone Information commands (CHGUSRTMZ, RMVUSRTMZ, and ADDUSRTMZ), respectively.

Please note the date and time information provided in the panel's upper right corner. This information is controlled by the current job's user profile's time zone information in accordance with the following rules:

If the user has no time zone information registered, the current system date and time is displayed.
If the user time zone and the system time zone are identical, the current system date and time is displayed.
If the user time zone is different from the system time zone, the system time is converted to the user's time zone and displayed.
If the user has time zone information registered and a Display Time Zone Information value of '*YES', the abbreviated name of the user's time zone is added to the time information.

You can perform the following test to see the effect of the user time zone information:

Run the WRKUSRTMZ command, specifying the name or prefix of the current job's user profile. For example:
```
     WRKUSRTMZ USRPRF(C*)
```
Add time zone information to the current job's user profile, specifying the system's time zone and *NO as the Display Time Zone Information setting. Press F5 to update the list, and the newly added user should appear.
From the list panel, use option 2 to change the current job's user profile's time zone, specifying a time zone having a different Coordinated Universal Time (UTC) offset, and press Enter.
When you return to the list panel, press F5 and notice the resulting change in the time information.
Repeat step 2, this time changing the Display Time Zone Information value to *YES.
Repeat step 3.

The retrieval of user application information and the conversion of date and time values are performed by functions included in the two service programs that I provided earlier, CBX152 and CBX153. Check out the previous articles for more details about these service programs.

The User Time Zone Information commands could easily be adapted or changed to support or maintain other types of user application information, should you ever have such a need.

Next time around, I continue my investigation of the UIM panel groups and APIs in yet another context, so stay tuned if your interest in that topic has been piqued.

This APIs by Example includes the following sources:

CBX153  -- User Time Zone Information Commands - services
CBX153B -- Service program binder source

These two sources have been updated to correct an error in the ChkTimZon() procedure. Please replace these sources in your utility library's source files. The CBX154M program ensures that the service program gets correctly recompiled.

CBX154  -- Work with User Time Zone Information - CPP        
CBX154E -- Work with User Time Zone Information - UIM Exit Program
CBX154H -- Work with User Time Zone Information - Help       
CBX154P -- Work with User Time Zone Information - Panel Group
CBX154V -- Work with User Time Zone Information - VCP        
CBX154X -- Work with User Time Zone Information - Command            

CBX154M -- Create Command Objects

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

For the Work with User Time Zone Information command to function correctly, all objects delivered in part one and two of this article need to be available on your system.

Part one of this article is here:
http://www.iseriesnetwork.com/article.cfm?id=52288

Part two of this article is here:
http://www.iseriesnetwork.com/article.cfm?id=52387

The API date and time zone support article is here:
http://www.iseriesnetwork.com/article.cfm?id=51703

Azubike Oguine's UIM articles are available here:
http://www.iseriesnetwork.com/artarchive/index.cfm?fuseaction=ListArticlesByAuthor&ID=367