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.

All versions of TIBCO Object Service broker for Open Systems will behave this way. Versions of TIBCO

Object Serice Broker for z/OS older than 5.0 HF 12 will behave differently. See Solution SOL1-CA7BAV

for details relevant to z/OS versions of OSB.

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:
========
At the time indicated above, the Shareable Tool $REALTIMER will begin generating values containing

sixteen digits, and which consequently will not fit in an 8-byte packed decimal representation. An

exception will be raised when an attempt is made to assign these values to an eight-byte packed decimal

field.


Resolution:
===========
If an application attempts to assign a value generated by $REALTIMER to an eight-byte packed decimal

field or parameter, then it will fail. If screens or reports contain fields of fifteen digits, and

values from $REALTIMER are assigned there, the values will not be displayed correctly.


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. Alternatively, you may wish to

use the tool SEARCHLIB, which does not depend upon a cross-reference. 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.

You will then need to examine the use put to the return value from each invocation of $REALTIMER, to

determine whether a sixteen-digit value will cause problems.

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.

6) Screens and reports need to be examined for fields that need to be widened to accommodate the extra

digit.


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