Abstract The whitepaper discusses the Optimized XT Reader which enables viewing of encyclopedia in Reader's mode using IBM Rational System Architect and also is a mandatory step to be able to use Encyclopedia with Cognos. Content This optimization involves 6 stages but information on what happens in each stage is currently not documented anywhere; hence, when this conversion fails, you are at a challenging state where you do not know what in the encyclopedia has changed and how to proceed. This document addresses this gap with the information gathered from some rigorous tests performed at Support labs. The document makes an attempt to capture all backed activities that occur during each stage. If optimization fails at any stage, the possible causes for the failure can easily be understood with the help of the information provided in this document and necessary action can be taken to prevent the same.

1. Understanding Optimized XT Reader
Mirtunjay Kumar Sharma
September 14, 2010
Page 1 of 15 “Rational Support Whitepaper”

2. INTRODUCTION.................................................................................................... 3
DIFFERENT STAGES FOR OPTIMIZED XT READER ........................... 4
STAGE 1: SET ENCYCLOPEDIA AS OPTIMIZEDXT READER .................................... 4
STAGE 2: SETUP ENCYCLOPEDIA SCHEMA .............................................................. 5
STAGE 3: UPDATE META DATA ................................................................................ 6
STAGE 4: UPDATE OPTIMIZED XT READER VIEWS ............................................... 6
STAGE 5: POPULATE ENTITYXML ............................................................................ 7
STAGE 6: DICTIONARY UPDATE ............................................................................... 7
STAGE 7: PROCESS DIAGRAMS ............................................................................... 8
OVERRIDING OPTIMIZED XT READER .................................................... 9
COMMON ISSUES AND SOLUTIONS ........................................................ 10
ERROR “UPGRADING ENCYCLOPEDIA TO OPTIMIZED XT READER SCHEMA” ..... 10
ERROR “THE ENCYCLOPEDIA CANNOT BE OPENED AS IT IS IT’S CURRENTLY
BEING UPGRADED.”.................................................................................................. 12
OPTIMIZED XT READER FAILS AT “POPULATE ENTITY XML” .............................. 13
CONCLUSION ....................................................................................................... 14
REFERENCES ......................................................................................................... 15
Page 2 of 15 “Rational Support Whitepaper”

3. Introduction
This whitepaper attempts to introduce
a. What “optimize XT Reader” does
b. The need to have an encyclopedia optimized and
c. Various stages involved to optimize an encyclopedia
To open an encyclopedia in reader mode using Rational System Architect XT, the
encyclopedia must be optimized using the functionality “optimize XT Reader”.
Optimizing allows encyclopedias to serve as data sources which support REST
API’s.
Optimized encyclopedia supports REST APIs which makes the encyclopedia
content available to other Rational Reporting products which use REST APIs such
as Rational Publishing Engine and Cognos for generating reports.
Rational System Architect v11.3.1 introduced the Optimized XT Reader
functionality. Encyclopedias created using Rational System Architect v11.3.1 with
either SQL Server 2005 or SQL Server 2008 as the backend will have Optimized
XT Reader enabled by default.
Page 3 of 15 “Rational Support Whitepaper”

4. Different Stages for Optimized XT Reader
Various stages and the actions performed in each step are detailed
below.
Figure 1: Snapshot showing the various stages
Stage 1: Set encyclopedia as OptimizedXT Reader
New property named “OptimizedXTReaderEnabled” is added to the
SAPROPERTIES table and the value for the property is set to “1”
Figure 2: Sample output of select* from SAPROPERTIES
Note: SAPROPERTIES is a table which consists of the basic information about an
encyclopedia. For example the type of encyclopedia such as professional or
enterprise.
Page 4 of 15 “Rational Support Whitepaper”

5. Stage 2: Setup Encyclopedia Schema
1. The underlying structure of an encyclopedia - the schema is added with
two properties “UpgradeState” and “UpgradeText”
2. It also updates certain fields in SAPROPERTIES table:
a. UpgradeState is set to 1
b. Last Metadata Table Update field is updated with date indicating the
time when the metadata table was updated. This field is in an
encoded format and hence the value does not look like a date.
c. UpgradeText will have a status statement
Figure 3: Sample output of showing values for properties “UpgradeState” and “UpgradeText”.
Page 5 of 15 “Rational Support Whitepaper”

6. Stage 3: Update Meta data
Metadata information for every class types (Diagram, definition and symbol) gets
added to the “Metadata” table to serve as a data source.
Stage 4: Update Optimized XT Reader Views
1. Views for each user who have permissions to access an Enterprise
encyclopedia get generated
2. Updates the “userviews” table with all the existing browser views in System
Architect.
Figure 4: Sample output of showing different user views
Page 6 of 15 “Rational Support Whitepaper”

7. Stage 5: Populate EntityXML
Entity table gets converted into XML format which would directly accessed by
SAXT users in reader mode. The data transformation into XML is done with the
help of “SP_SA_AddPropertiesXMLColumn” stored procedure.
Figure 5: Sample output of EntityXML table.
Note: Huge encyclopedia may take hours to be converted into XML format
Stage 6: Dictionary Update
In the previous stages (1-5), the structure of the encyclopedia and the content
are modified supporting REST APIs. To make sure the modified content does not
have inconsistencies a Dictionary Update is run to resolve inconsistencies.
Below are a few things checked during “Dictionary Update”:
1. Searches the dictionary for all undefined data elements and structures
2. Searches the dictionary for all dictionary entities without a correct
relationship to the entity of which they are a part. For example, it searches
for data elements whose relationships to data structures are not correctly
defined.
3. As much as possible, it will correct the errors following the parameters of
the Property Configuration Set and the USRPROPS.TXT file.
4. Searches the dictionary for undefined data or expressions.
5. Creates and displays a report listing rules violations that could not be fixed
and entities that were fixed. You can print this report.
Page 7 of 15 “Rational Support Whitepaper”

8. Stage 7: Process Diagrams
Each diagram in an encyclopedia gets processed to create an equivalent ".svg"
file which is saved in the FILES table.
Figure 6: Sample output of files table from an encyclopedia
Page 8 of 15 “Rational Support Whitepaper”

9. Overriding Optimized XT Reader
If there is a need to migrate the encyclopedia (like SQl to Oracle), you have to
override XT Reader conversion because SAMIGRATE tool at present does not
support Optimized XT Reader enabled encyclopedias.
One can override the Optimized XT Reader by editing SA2001.ini file from your
local profile:
1. Open the SA2001.INI file, located in the following default directory:
C:Documents and Settings<UserName>Local SettingsApplication
DataTelelogicSystem Architect.
2. Create a heading named [SystemArchitect], if one does not exist already.
3. Add the following line under the [SystemArchitect] heading:
OverrideOptimizedXTReader=Y
4. Save and close the SA2001.INI file. The override will take effect the next
time you start Rational System Architect.
Page 9 of 15 “Rational Support Whitepaper”

10. Common issues and Solutions
Error “Upgrading Encyclopedia to Optimized XT Reader
Schema”
Figure 7: Error message while opening an encyclopedia
Possible Scenario:
Error is seen while opening an encyclopedia in Rational System Architect.
Diagnosing the problem
1. Open SAEM or SQL Server Management Studio
2. Connect to the SQL Server instance where the encyclopedia resides
3. Select the encyclopedia and execute a query [select *from
SAPROPERTIES] and observe the result.
Figure 8: Showing the content of SAPROPERTIES table.
Page 10 of 15 “Rational Support Whitepaper”

11. 4. Observe if the value for the fields “OptimizedXTReaderEnabled” and
“UpgradeState” is set to 1 and “UpgradeText” has some text. The
Optimize XTReader operation is failed due to some reason. You need to
change the values in the saproperties table and run the optimize XTReader
again.
Solution:
1. Update saproperties set value=’0’ where
name=’OptimizedXTReaderEnabled’
2. Update saproperties set value=’0’ where name=’UpgradeState’
3. Update saproperties set value=’’ where name=’UpgradeText’
Now, run optimized XTReader operation again and ensure that process should be
completed.
Page 11 of 15 “Rational Support Whitepaper”

12. Error “The encyclopedia cannot be opened as it is it’s
currently being upgraded.”
Figure 9: Error message while opening an encyclopedia
Possible Scenario:
Error is seen while opening an upgraded encyclopedia in Rational System
Architect.
Diagnosing the problem:
This error generally occurs if Optimize XTReader process is successful however
the upgrade text field is not updated due to some reason.
Solution:
Clear the upgrade text field in SAPROPERTIES table by running a query
Update saproperties set value=’’ where name=’UpgradeText’
Now, the encyclopedia should be open.
Page 12 of 15 “Rational Support Whitepaper”

13. Optimized XT Reader fails at “Populate Entity XML”
Figure 10: Snapshot showing the stage where the Optimized XT Reader fails
Possible Scenario:
Usually observed during the upgrade of an encyclopedia in System Architect.
Causes:
This error generally occurs if any of the following condition is true.
1. Not enough disk space in C drive.
2. File growth is not set of Auto growth option for TEMPDB database.
Solution:
1. Ensure that you have enough disk space available in C drive.
2. Verify that the file growth is set of “AUTOGROWTH”
Page 13 of 15 “Rational Support Whitepaper”

14. Conclusion
The “Optimized XT Reader” option is required to make the content of the
encyclopedia to be REST enabled.
The information about backend activities being performed in each stage would
help to understand the reason for failure in case the optimization process fails
and hence be in a better position to resolve it.
Having REST enabled opens up wide range of opportunities and scope of usage of
Rational System Architect’s Encyclopedia data. Important Data gathered though
Enterprise Modeling in Rational System Architect can then serve as input to
Business Analytics / Intelligence capable tools to pull out very useful analysis to
take the Enterprise to its next level or fix current issues. All new encyclopedias
created using System Architect version 11.3.1 are thus already enabled for XT
Reader which means they come REST enabled and ready for playing a bigger role.
Page 14 of 15 “Rational Support Whitepaper”

15. References
 Rational System Architect online help
 Rational System Architect XT online help
 http://en.wikipedia.org/wiki/Representational_State_Transfer
Page 15 of 15 “Rational Support Whitepaper”