Today's issue of APIs by Example provides three User Time Zone Information commands that let you easily maintain time zone information for any user profile: The Add, Change, and Remove User Time Zone Information commands -- ADDUSRTMZ, CRTUSRTMZ, and RMVUSRTMZ, respectively.

More important, these commands also enable an upcoming demonstration of how user application information can be used to control the behavior or configuration of an application or utility.

Time zone information is as such only one example of the type of information that the V5R3 User Application Information APIs are capable of storing with -- and retrieving from -- a user profile.

For more information about the User Application Information APIs, please read the previous installment of this article -- just follow the link at the end of this article.

All we need to know for now is that although the APIs handle the user application data, it is up to the programmer to actually define the data structure used to store and retrieve the specific application data. So before we look at the commands, let me present the user time zone information, which I store in a data structure that has the following layout:

  **-- Time zone user application information:                    
  D TimZonUai       Ds                  Qualified                
  D  FmtLen                       10i 0 Inz( %Size( TimZonUai )) 
  D  FmtNam                        8a   Inz( 'TIMZ0100' )        
  D  Resv1                         4a                            
  D  TimZon                       10a                            
  D  TimZonAbr                    10a                            
  D  DspAbrTimZon                  4a                            
  D  Resv2                        88a                            

The Add and Change User Time Zone Information commands use only the TimZon (Time Zone) and DspAbrTimZon (Display Abbreviated Time Zone) fields, because these are the only data that these commands can set. But other fields have been added to facilitate future changes to, and safe retrieval of, the data structure.

The FmtLen (Format Length) field makes it possible to ensure that any program retrieving the information knows exactly how much data is available and therefore should be accessed. Likewise, the FmtNam (Format Name) field can be checked to see if the data structure has the expected layout. Future requirements can also be easily supported by adding new formats, and include a format parameter when retrieving the data, to define the format to be returned.

Finally, two reserved fields have been added to allow for new fields to be included, without being forced to introduce a new format. These concepts are well known from API programming in general and provide robustness and flexibility to application design.

The CBX152 service program that I included last time exports the set of procedures required to perform all User Application Information API interaction:

SetUsrTimZon() -- Creates or updates user time zone information
VfyUsrTimZon() -- Verifies user time zone information
GetUsrTimZon() -- Retrieves user time zone information
DltUsrTimZon() -- Removes user time zone information

The new CBX153 service program offers a number of procedures to perform time zone command related functions:

ChkTimZon()  -- Checks whether the specified time zone is registered
GetTimZonA() -- Retrieves the abbreviated name of a time zone
GetZonDts()  -- Retrieves a timestamp for the specified time zone
CvtZonDts()  -- Converts a timestamp from one time zone to another 
GetSysVal()  -- Retrieves the specified system value
ChkObj()     -- Checks for object existence

The prompt of the ADDUSRTMZ command has the following appearance:

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

            Add User Time Zone Information (ADDUSRTMZ)           
Type choices, press Enter.                                             
User profile . . . . . . .                 Name                  
Time zone  . . . . . . . .                 Q0000GMT, Q0000GMT2...
Display time zone  . . . .   *NO           *NO, *YES             

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

Specify a user profile name, a valid time zone name, and whether the abbreviated form of the time zone name should be displayed together with date and time information on screens and reports. When the cursor is in the time zone field and F4 is pressed, the command uses a choice program to list all valid time zones as well as their respective descriptions.

The Change User Time Zone command is similar to the ADDUSRTMZ command, except for the addition of a prompt override program to retrieve the current User Time Zone Information values when the user profile name has been specified.

Please note that due to the authority restrictions of the User Application Information APIs, all three commands require *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.

To have access to all User Time Zone Commands in one place, I created the CMDUSRTMZ menu, following the IBM standard recipe for grouping related commands in a CMD* menu:

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

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  
  Related Command Menus                                                        
    10. Time Zone Description Commands                  CMDTIMZON  
                                                           Bottom 
Selection or command                                                           
===>                                                                           
F3=Exit   F4=Prompt   F9=Retrieve   F12=Cancel                                 

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

After you complete the creation of all command objects using the CBX153M program (read on), simply type GO CMDUSRTMZ on a command line and press Enter. As always, help text is provided for both menu and commands.

Next time, in the final installment of this article series, I add a new Work With User Time Zone Information command, which serves two purposes, the most obvious being an interface to work with all user profiles that have time zone information registered with them. Another more interesting (in this context) purpose is to show how the date and time information displayed on the command's list panel can be controlled by the current user's time zone information setting.

This APIs by Example includes the following sources:

CBX152   -- User Application Information APIs - services
CBX152B  -- Service program binder source
CBX153   -- User Time Zone Information Commands - services
CBX153B  -- Service program binder source

CBX153U  -- User Time Zone Information Commands Menu
CBX153C  -- User Time Zone Information - Choice Program

CBX1531  -- Add User Time Zone Information - CCP              
CBX1531H -- Add User Time Zone Information - Help             
CBX1531V -- Add User Time Zone Information - VCP              
CBX1531X -- Add User Time Zone Information                    

CBX1532  -- Change User Time Zone Information - CCP     
CBX1532H -- Change User Time Zone Information - Help    
CBX1532O -- Change User Time Zone Information - POP     
CBX1532V -- Change User Time Zone Information - VCP     
CBX1532X -- Change User Time Zone Information           

CBX1533  -- Remove User Time Zone Information - CCP  
CBX1533H -- Remove User Time Zone Information - Help 
CBX1533V -- Remove User Time Zone Information - VCP  
CBX1533X -- Remove User Time Zone Information        

CBX153M  -- Create Command Objects

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

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

This article demonstrates the following APIs:

User Application Information APIs:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/misc1c.htm

Update User Application Information (QsyUpdateUserApplicationInfo) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qsyupdui.htm

Retrieve User Application Information (QsyRetrieveUserApplicationInfo) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qsyrtvui.htm

Remove User Application Information (QsyRemoveUserApplicationInfo) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qsyrmvui.htm

Send Program Message (QMHSNDPM) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/QMHSNDPM.htm

Retrieve Time Zone Description (QWCRTVTZ) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwcrtvtz.htm

Retrieve System Time Information (QWCRTVTM) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwcrtvtm.htm

Convert Date and Time Format (QWCCVTDT) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwccvtdt.htm

Retrieve System Values (QWCRSVAL) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qwcrsval.htm

Retrieve Object Description (QUSROBJD) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/qusrobjd.htm

Check User Special Authorities (QSYCUSRS) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/QSYCUSRS.htm

You can retrieve the source code for this API example from http://www.pentontech.com/IBMContent/Documents/article/52387_65_UserAppInfo2.zip.