Resolution:
Description:
============
The Shareable Tool $REALTIMER will exceed 15 digits on Friday September 9th 2011 when the hardware clock reaches 01:46. The actual time at which this will happen will depend upon the local time-zone, and whether or not the clock is set to Universal Co-ordinated Time.
Application code may have been written that stores values returned by $REALTIMER in an eight byte packed decimal field or parameter. Such applications will fail at that time. This application vulnerability and the recommended fixes have previously been described in the following LBNs: LBN1-ARXBRV, LBN1-AJEW6S, LBN1-BS1CXC, LBN1-ARHV83, and LBN1-C3L0JI.

This article describes how to inspect an application for vulnerability to this event, and summarizes how to fix the application. It also describes two simple ways to simulate the event in testing, to ensure that application code is not vulnerable to the rollover.


Symptom:
========
In pre-5.0 HF 12 versions of OSB, the value returned by $REALTIMER will wrap to zero and resume counting from there. In 5.0 HF 12 and later versions, it will return a correct value, which will contain sixteen digits, and which consequently will not fit in an 8-byte packed decimal representation.


Resolution:
===========
If you are running a pre-5.0 HF 12 version of OSB, the value returned by $REALTIMER will wrap to zero and resume counting from there and you *may* not need to do anything. It really depends upon whether you depend upon the $REALTIMER values always remaining in numerical order. You must inspect your application code to determine this.

In 5.0 HF 12 and later versions, the attempt to assign a 16 digit value into an eight-byte packed representation is what will fail. If you do not do this, you’ll be okay.

Inspecting an application for vulnerability:
Use the REFMAKER shareable tool to generate a cross-reference of your application (SITE) library, then use SEARCH and CROSSREFSEARCH tools to look for instances of $REALTIMER. The OSB UI also incorporates search facilities, if you prefer to use it instead, in which case you do not need to generate a cross-reference of your application (SITE) library.

If you do need to update your application, further hot fixes are necessary to enable the table and screen definers, as well as the offline utilities, to properly deal with the wider packed fields you will have to add to your application. These hotfixes are available for all currently supported releases.

   o TIBCO Object Service Broker for Open Systems ver 5.0.0
   o TIBCO Object Service Broker for Open Systems ver 5.2.0
   o TIBCO Object Service Broker for z/OS, ver 5.0.0  
   o TIBCO Object Service Broker for z/OS, ver 5.2.0
  
You are encouraged to maintain your installation at the latest hotfix level.

As to the application changes themselves, they’re conceptually very simple. All eight-byte packed decimal fields that receive values generated by $REALTIMER will have to be widened to make room for the extra digit. A single extra byte (packed 9) will last you around 300 years.

The specific issues to look for in the code are as follows.
1) If full $REALTIMER values are stored then the length of the fields will need to be increased. The length of non-key fields can simply be increased in the table definition.

2) Tables where $REALTIMER values are part of the primary key will need to be unloaded, cleared, changed and reloaded. Many customers may find it more convenient to create a new table definition with a different name and with the revised field/parameter definitions, and copy the data, rather than unloading and loading.

3) Tables where $REALTIMER values are part of a secondary key will need the secondary key to be removed before the change and then rebuilt.

4) Parameterized tables where a $REALTIMER value is used as a QP8 Data Parameter value will need to be unloaded, cleared, the length of the Data Parameter changed and reloaded.

5) If parameterized tables are changed as per 4) above, the DOB should be recycled so that any PRM tables for these changed parameterized tables will reflect the changes.


Testing an application for vulnerability to $REALTIMER rollover
===============================================================

Since applications commonly assume that $REALTIMER will never return the same value twice, both approaches provided as samples below include a mechanism for guaranteeing uniqueness.

An Object Service Broker rule will be interpreted before a shareable tool with the same name. To take advantage of this fact create a rule named $REALTIMER, that will generate values longer than 15 digits. A sample is provided below. Placing the rule in your SITE library, with the name $REALTIMER, will cause application code to invoke it instead of the shareable tool. You will probably find it useful to initially give the rule some other name, so that you can test it without usurping the $REALTIMER behaviour. Then, rename it to $REALTIMER and place it in your SITE library to test your application.

Using a SES table
-----------------
This approach guarantees that the values returned by the new $REALTIMER rule will be unique within an OSB session.

Here is the rule.

$REALTIMER;                                                      
_                                                    
_ ----------------------------------------------------------------
_ ------------------------------------------------------------+---
_ GET TIMETABLE WHERE KEY = 1;                                ¦ 1
_ TIMETABLE.TIMER = TIMETABLE.TIMER + 123;                    ¦ 2
_ REPLACE TIMETABLE;                                          ¦ 3
_ RETURN(TIMETABLE.TIMER);                                    ¦ 4
_ ----------------------------------------------------------------
_ ON GETFAIL TIMETABLE :                                          
_    TIMETABLE.KEY = 1;                                          
_    TIMETABLE.TIMER = '1000000000456780';                        
_    INSERT TIMETABLE;                                            
_    RETURN(TIMETABLE.TIMER);                                    


Here is the associated table.

        Table: TIMETABLE        Type: SES   Unit: MACRAER           IDgen:  N  
                                                                                
    Parameter Name  Typ Syn Len Dec Class            '      Event Rule   Typ Acc
   ----------------  -   -- --- --    -              '   ---------------- -   -
_                                                   ' _                        
_                                                   ' _                        
      Field Name   Typ Syn  Len Dec Key Ord Rqd    Default         Reference    
   ---------------- -   -- ----- --  -   -   - ---------------- ----------------
_ KEY              I   B      2  0  P                                          
_ TIMER            Q   P     10  0                      


Using an EES table
------------------

This is a slightly more sophisticated approach, using an EES table to guarantee that unique values will be generated for all sessions in an EE. EES tables are supported at and after OSB version 5.0.0.

There are three rules:

$REALTIMER;                                                      
_ LOCAL TIMER;                                                    
_ ----------------------------------------------------------------
_ ------------------------------------------------------------+---
_ UNTIL REALTIMEROK:                                          ¦ 1
_     CALL REALTIMER2;                                        ¦
_     END;                                                    ¦
_ RETURN(TIMER);                                              ¦ 2
_ ----------------------------------------------------------------
_


REALTIMER2;                                                      
_                                                  
_ ----------------------------------------------------------------
_ ------------------------------------------------------------+---
_ GET TIMETABLE WHERE KEY = 1;                                ¦ 1
_ TIMETABLE.TIMER = TIMETABLE.TIMER + 123;                    ¦ 2
_ REPLACE TIMETABLE;                                          ¦ 3
_ TIMER = TIMETABLE.TIMER;                                    ¦ 4
_ SIGNAL REALTIMEROK;                                         ¦ 5
_ ----------------------------------------------------------------
_ ON GETFAIL TIMETABLE :                                          
_    CALL REALTIMER3;
_ ON LOCKFAIL :  


REALTIMER3;                                                      
_ ----------------------------------------------------------------
_ ------------------------------------------------------------+---
_ TIMETABLE.KEY = 1;                                          ¦ 1
_ TIMETABLE.TIMER = '1000000000456780';                       ¦ 2
_ INSERT TIMETABLE;                                           ¦ 3
_ ----------------------------------------------------------------
_ ON INSERTFAIL :  


Here is the table:

      Table: TIMETABLE        Type: EES   Unit: MACRAER           IDgen:  N
                                                                            
  Parameter Name  Typ Syn Len Dec Class            '      Event Rule   Typ A
----------------  -   -- --- --    -              '   ---------------- -  
                                                   ' _                      
                                                   ' _                      
    Field Name   Typ Syn  Len Dec Key Ord Rqd    Default         Reference  
---------------- -   -- ----- --  -   -   - ---------------- --------------
KEY              I   B      2  0  P                                        
TIMER            Q   P     10  0                                          
@@UPDATE_COUNT   Q   B      4  0                                          
@@REF_COUNT      Q   B      4  0

How to check an application for vulnerability to the $REALTIMER rollover.