Gen Encyclopedias and importance of unique Encyclopedia IDs

search cancel

Gen Encyclopedias and importance of unique Encyclopedia IDs

book

Article ID: 55615

calendar_today

Updated On:

Products

Gen Gen - Host Encyclopedia

Issue/Introduction

Introduction
What are Encyclopedia IDs?
The importance of unique encyclopedia Ids
What is the current value of the Encyclopedia ID
Multiple CSEs

Introduction

You have already has at least one Gen Host Encyclopedia (HE) or Client Server Encyclopedia (CSE) and you plan to install another one.

How do you answer the questions?

What Encyclopedia ID should be given to the new encyclopedia?
Does the new Encyclopedia ID need to be unique?

In this article, these items will be dicussed:

Why unique encyclopedia IDs are important and what may happen if they are not unique.
How to determine the values of your current encyclopedia IDs and what steps need to be done if they are not unique.

What are Encyclopedia IDs?

In the CSE, the Encyclopedia ID is assigned during encyclopedia configuration and is preserved during encyclopedia upgrades. The Encyclopedia ID value can be changed after the encyclopedia has been in use; but the new Encyclopedia ID only applies to objects created after the change occurred.
The Original Encyclopedia ID for a new object is the current Encyclopedia ID.
The Original Object ID for a new object is the same value as the object ID.
The combination of the Original Encyclopedia ID and Original Object ID is known as the "Org ID".

During various encyclopedia operations that preserve or assign ancestry, the Org ID values of an object are assigned from an equivalent object in another model. Within an encyclopedia, CSE enforces uniqueness of Org IDs, each Org ID cannot occur more than one time in each model, but it can occur in more than one model. The Org ID can continue to exist as a reference to an ancestral object even when that ancestral object no longer exists. Although CSEs cannot enforce it, the intent is that Org IDs have the same uniqueness across all encyclopedias. Org IDs can continue to exist and be transported with models even if the original object in which the Org ID came into existence has been deleted.

The importance of unique encyclopedia Ids

In the CSE the Encyclopedia ID becomes part of the information used to identify objects from 2 different models that are related.
In the HE, the ID is used when objects are extracted from the HE to be loaded as a child in a CSE.

When any of the following tasks are done:

Models are copied within the same encyclopedia.
Part of a model is extracted from one encyclopedia to another with the intent of applying changes back to the parent encyclopedia
A CSE model is moved to another CSE with the 'download with upload & extract options', the ancestry of the objects in the model is taken with the model so that the software knows when 2 objects from different models are related. ***intent not to maintain a parent/child link***

In a CSE, the ancestry of an object is made up of the original Encyclopedia ID and the original object ID. If you have multiple encyclopedias set with the same Encyclopedia ID and are moving models across them, you have the potential to create objects in 2 different models that look like they are related but in fact do not have a relationship (they could actually be different object types)

What is the current value of the Encyclopedia ID

How can the Encyclopedia ID be determined for a given encyclopedia?

On the HE:
The default HE Encyclopedia ID is 1 but in practice, it may be different (Configuring Host Encyclopedia and Host Construction > Configuration Variables).
To check the value:
From the Main Menu select "5. Environment specification" -> "5. Display system information" -> "1. Host Encyclopedia variables."
Alternatively, run the following SQL against the DMAX table to find out the value of the encyclopedia ID:
select max_value from DMAX where max_mnemonic = 'ENCYNAME';

On the CSE:
Login to the Support Client & select Utilities/Set Local Encyclopedia ID.
Alternatively, run the following SQL against the DMAX table to find out the value of the encyclopedia ID:
select max_int_value from DMAX where max_type = 'ENCYNAME';

Multiple CSEs

Now, consider the case of a company with several encyclopedias that have the same Encyclopedia ID and what may happen. The company has an encyclopedia for the prior version of the Gen software and has decided to create a new encyclopedia for the current software. When installing the new encyclopedia, the administrator did not think that the 2 encyclopedias would be related since the company does not extract child models from a parent encyclopedia and apply changes back to the parent. So, the encyclopedia IDs for both CSEs were set to 1. In order to move some of the models from the prior version CSE to the current version CSE, the users did the 'download with upload & extract options' so that the models in the current version CSE would have ancestry without having to adopt the models. Any model that was uploaded into the current encyclopedia with the 'download with upload & extract options' will have an original Encyclopedia ID of 1 and the original object ID that came from the prior version CSE. As the customer starts creating objects within models or creating new models within the current version CSE all of the objects created will be given an original Encyclopedia ID of 1 and an original object ID value that matches the object ID. So potentially any of the new objects created may have object IDs that match the original object ID of the objects contained in the models extracted from the previous encyclopedia, thus creating a false ancestry. When the customer starts trying to migrate objects between models, they may see the following types of problems:

The migration may complete successfully but the aggregate object in the destination model is corrupted with object associated incorrectly to wrong types of objects because the migration found a related object but the related object in the destination model was not the same type of object as in the source model.
The migration may fail with migration errors of objects needing related objects but migrating more aggregates does not clean up the migration errors. This situation is also caused because the destination model contained an object that was related by ancestry but was a different type of object.
The migration may fail with a DBMS duplication problem such as a SQL -803 or ORA-00001: unique constraint (ENCY.DOBJI3) violated. This error will happen when a new object is being created and the model already has an object in it that has the same original Encyclopedia ID and original object ID.
Check-in of updates to a subset or model can also fail with the unique constraint (ENCY.DOBJI3) violated error. When the update contains objects just added to the model from the toolset or child model, the new values for original object ID can overlap with values already assigned in the model. These new objects may also have values that overlap with Original Object IDs in other models; which would go undetected until some kind of adoption or migration action is attempted.

Environment

Gen Host Encyclopedia
Gen Client/Server Encyclopedia (CSE)

Cause

How to check if my current CSE has problems?

After you have determined what your current encyclopedia(s) is using for its ID, you may want to look to see if you have any situations where models may have been loaded into an encyclopedia and retained the ancestry. This scenario will only apply to a CSE as it is not possible to load models with retained ancestry into a HE.

Are there any original object IDs, with original ency ID equal to the current CSE ency ID, which are greater than the current allocated maximum object ID?

Run the following command on the CSE server:

initdb -c "DBNAME=<dbname> DBUSER=<user> DBPSWD=<password>" -r

NOTE: "DBNAME=<dbname> DBUSER=<user> DBPSWD=<password>" represents the connection information for the Encyclopedia Database and should match the corresponding line "DBNAME=..." from the CSE iefmd.ini file.

The output of initdb will be of the form:

Object ID Partition Status:

Part 1 min= 1 max= <max_obj_id>

next= <next_obj_id> DOBJ max=<dobj_max_obj_id>

Part 2 .....

1. For each partition listed run an SQL statement of the form:
select obj_org_obj_id from DOBJ
where obj_org_obj_id between < next_obj_id> and < max_obj_id > and obj_org_ency_id= (select max_int_value from DMAX where max_type='ENCYNAME');

If any rows are returned then there is a problem.

2. Are there objects that have the same ancestry but have different object type codes?
Run this SQL:
select mdls.model_name, src.obj_id, src.obj_type_code, mdld.model_name, dest.obj_id, dest.obj_type_code
from DOBJ src, DOBJ dest, DMDL mdls, DMDL mdld where src.obj_org_ency_id = dest.obj_org_ency_idand src.obj_org_obj_id = dest.obj_org_obj_idand src.obj_type_code <> dest.obj_type_codeand mdls.model_id = src.obj_model_idand mdld.model_id = dest.obj_model_id;
If any rows are returned then there is a problem.

Correcting CSE 'ancestry corruption'

We will look at the steps that need to be done if you have 2 CSEs with the same Encyclopedia ID and have been moving models between them. For the commands mentioned in the instructions below please refer to the Client Server Encyclopedia Guides for more details.

Significant development work not already done on new CSE (any work will have to be redone after correction)

In this scenario no significant development work has already been done on the new CSE & it is acceptable that any such work can be lost i.e. the original extracted models can be reloaded & override the work already done.

Make sure that the new CSE is stopped
Gen 6.5
Start the install script for the CSE by running the installation setup program. From the installation menu select option 'F Initialize Database Encyclopedia Server'. This option will

Drop and recreate the encyclopedia tables.
Load the Public Interface views - if desired.
Run the initdb program which allows you to specify the CSE ID (ensure that an ID different to the existing CSE is used here), Name and admin ID.
Load the schema tables.

Gen 7.x and 8.x
Start the configuration script for the CSE by running cse_config which is located in CSE bin folder. Choose option 'Initialize Existing Encyclopedia Tables' & also specify a unique value for Encyclopedia ID field (ensure that ID is different to any existing CSE)
This option will

Truncate existing data tables, keeping prior table properties.
Load the schema tables.
Initialize the required data tables with configuration data.

Restart the new CSE
Using the Coordination Client connect to the new CSE and register the CSE created in step 2. Also grant the existing UserID in the Co-ordination database access rights to this new CSE.
Using the Encyclopedia Client connect to the new CSE and add the required userIDs to it.
Extract the required models from the existing CSE using the following command
download -u <userID> -m <model> [-s <subset>] -l -t extract [-d <directory>]
Copy (ftp binary) the extracted model tran files to the new CSE machine
Load the extracted models into the new CSE using the command
upload -u <userID> -t apply -d directory
Convert the loaded models to new schema release (if required) using the command
convall -u <userID>
Run the following SQL to ensure no rows are returned.
select mdls.model_name, src.obj_id, src.obj_type_code, mdld.model_name, dest.obj_id, dest.obj_type_code from DOBJ src, DOBJ dest, DMDL mdls, DMDL mdld where src.obj_org_ency_id = dest.obj_org_ency_id and src.obj_org_obj_id = dest.obj_org_obj_id and src.obj_type_code <> dest.obj_type_code and mdls.model_id = src.obj_model_id and mdld.model_id = dest.obj_model_id;

Significant work already done on new CSE

In this scenario significant development work has already been done on the new CSE & this work is required to be retained i.e. it is not acceptable to reload the original extracted models & override the work already done. In this case it is not possible to cleanup the ancestry corruption & retain the original ancestry; the updated models must be downloaded from the new CSE with no ancestry & then uploaded & adopted to regain ancestry.

Option 1 (retain original models in CSE during reload)

Stop all development work & checkin all subsets.
Take backup of CSE databases
Change ency ID on CSE to unique value i.e. it should be different to any of your other CSEs.
This should be done as follows:
Using Coordination Client (Encyclopedia/Open/Modify)
Using Support Client run option Utilities/Set Local Encyclopedia ID.
Run SQL against encyclopedia database
update DENCY set ency_id=<new ency ID>;
commit;
To verify ency ID has been changed in all required places run SQL as follows:
Coordination Database:
select de_id from DIRENCY;
select dl_ency_id from DIRLOGON;
Encyclopedia Database:
select max_int_value from DMAX where max_type='ENCYNAME';
select ency_id from DENCY;
For all existing models, download using the following command. This will create an update.trn for each model.
download -u <userID> -m <model> -l -d <directory>
Rename existing models on CSE.
Upload each model downloaded in step 4.
upload -u <userID> -d <directory>
Adopt all models to recreate ancestry information.
For detailed information on adoption, please see Client Server Encyclopedia Version Control Guide. Essentially for each group of models you have in the CSE you need to perform adoption tasks to enable common ancestry. 'Group of models' means models that you do migrations across e.g. development, test, production versions of a model. The models in that group need to be adopted to have common ancestry for version control tasks like migration. Within that group you need to choose 1 model as the source of the adoption & the others will be the destination. So for each model in the group, apart from 1 (the source model), you need to adopt the source model to that other model (destination model).
After you are happy with new models accessibility, delete original models.
Run the following SQL to ensure no rows are returned.
select mdls.model_name, src.obj_id, src.obj_type_code,
mdld.model_name, dest.obj_id, dest.obj_type_code
from DOBJ src, DOBJ dest, DMDL mdls, DMDL mdld
where src.obj_org_ency_id = dest.obj_org_ency_id
and src.obj_org_obj_id = dest.obj_org_obj_id
and src.obj_type_code <> dest.obj_type_code
and mdls.model_id = src.obj_model_id
and mdld.model_id = dest.obj_model_id;

Option 2 (remove original models from CSE prior to reload)

Stop all development work & checkin all subsets.
Take backup of both CSE databases
For all existing models, download using the following command. This will create an update.trn for each model.
download -u <userID> -m <model> -l -d <directory>
Rebuild the Encyclopedia database (deletes original models)
Gen 6.5
Start the install script for the CSE by running the installation setup program. From the installation menu select option 'F Initialize Database Encyclopedia Server'. This option will:
Gen 7.x & 8.x
Start the configuration script for the CSE by running cse_config which is located in CSE bin folder. Choose option 'Initialize Existing Encyclopedia Tables' & also specify a unique value for Encyclopedia ID field (ensure that ID is different to any existing CSE)
This option will:
Restart the new CSE.
Using the Coordination Client connect to the new CSE and register the CSE created in step 4. Also grant the existing UserID in the Co-ordination database access rights to this new CSE.
Using the Encyclopedia Client connect to the new CSE and add the required userIDs to it.
Upload each model downloaded in step 3
upload -u <userID> -d <directory>
Adopt all models to recreate ancestry information.
For detailed information on adoption, please see Client Server Encyclopedia Version Control Guide. Essentially for each group of models you have in the CSE you need to perform adoption tasks to enable common ancestry. The term 'Group of models' means models that you do migrations across e.g. development, test, production versions of a model. The models in that group need to be adopted to have common ancestry for version control tasks like migration. Within that group you need to choose 1 model as the source of the adoption & the others will be the destination. So for each model in the group, apart from 1 (the source model), you need to adopt the source model to that other model (destination model).
Run the following SQL to ensure no rows are returned.
select mdls.model_name, src.obj_id, src.obj_type_code,
mdld.model_name, dest.obj_id, dest.obj_type_code
from DOBJ src, DOBJ dest, DMDL mdls, DMDL mdld
where src.obj_org_ency_id = dest.obj_org_ency_id
and src.obj_org_obj_id = dest.obj_org_obj_id
and src.obj_type_code <> dest.obj_type_code
and mdls.model_id = src.obj_model_id
and mdld.model_id = dest.obj_model_id;

Changing Encyclopedia ID

If you have just created your CSE but have not started working in it and will now be extracting models/subsets from your HE, how do you change the Encyclopedia ID if they are the same?

HOST Encyclopedia

Once you are in the encyclopedia, do the following command from the command line

----------------------- ISPF/PDF PRIMARY OPTION MENU ------------------------

OPTION ===> tso %tiemax

The following panel will be displayed:

Reset MAX values table

COMMAND ===>

Enter the schema table release or blank

Enter the encyclopedia name or blank

Enter the Encyclopedia ID or blank

F1=Help F3=Exit F12=Cancel

You will need to put an integer value in the encyclopedia field and press enter.

To verify that the value was updated, run the following SQL:
select max_value from DMAX where max_mnemonic = 'ENCYNAME';

CSE
The Encyclopedia ID needs to be changed in multiple places as follows:

Using Coordination Client (Encyclopedia/Open/Actions/Modify)
Using Support Client run option Utilities/Set Local Encyclopedia ID.
Run SQL against encyclopedia database
update DENCY set ency_id=<new Ency ID>;
commit;

To verify new Encyclopedia ID against Encyclopedia Name run SQL as follows:
Coordination Database:
select de_id, de_long_name from DIRENCY;
select distinct dl_ency_id from DIRLOGON;

Encyclopedia Database:
select max_int_value from DMAX where max_type='ENCYNAME';
select ency_id from DENCY;

Purchased/External Models

If you will be purchasing models or receiving models from a source outside your company, we strongly recommend that they come to you in an upload format. Since the upload format does not contain ancestry information, you will not have to be concerned with whether there is a conflict with your encyclopedia ID. However, if you wish to have the model related to other models in your encyclopedia, you will need to adopt the purchased/external model.

Additional Information

This article can also be relevant for Encyclopedia upgrades.

During the upgrade phase it may be planned to have old and new Encyclopedias running in parallel with work being done in both and subsequently any modified models in the old Encyclopedia needing to be copied to the new Encyclopedia. For that scenario both Encyclopedias must either have unique IDs or any copied models must be downloaded from the old Encyclopedia without retaining ancestry (extract option not used) and after upload to the new Encyclopedia they will then need to be adopted to regain ancestry.

Feedback

thumb_up Yes

thumb_down No