Your company already has at least one encyclopedia 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, we will discuss:

 - 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 a Client/Server Encyclopedia (CSE) the Encyclopedia ID becomes part of the information used to identify objects from 2 different models that are related.

 - In the Host Encyclopedia (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 (Gen™ 8.6 > Installing > Install Gen on z/OS > 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:

1. 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.
2. 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.
3. 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.
4. 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.

Release: 6.5, 7.x, 8.x

Component: Gen Host Encyclopedia,  Gen Client/Server Encyclopedia (CSE)

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 .....

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.

Are there objects that have the same ancestry but have different object type codes?

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;

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.

1. Make sure that the new CSE is stopped
   
   
2. 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 Encyclopaedia Server'. This option will 
   
   
1. Drop and recreate the encyclopedia tables
2. Load the Public Interface views - if desired
3. 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
4. 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 Encyclopaedia Tables' & also specify a unique value for Encyclopedia ID field (ensure that ID is different to any existing CSE) 
This option will

5. Truncate existing data tables, keeping prior table properties
6. Load the schema tables.
7. Initialize the required data tables with configuration data.
   
   
2. Restart the new CSE
   
   
3. 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.
   
   
4. Using the Encyclopedia Client connect to the new CSE and add the required userIDs to it.
   
   
5. Extract the required models from the existing CSE using the following command 
   download -u <userID> -m <model> [-s <subset>] -l -t extract [-d <directory>] 
   
   
6. Copy (ftp binary) the extracted model tran files to the new CSE machine
   
   
7. Load the extracted models into the new CSE using the command 
   upload -u <userID> -t apply -d directory 
   
   
8. Convert the loaded models to new schema release (if required) using the command 
   convall -u <userID> 
   
   
9. 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)

1. Stop all development work & checkin all subsets.
   
   
2. Take backup of CSE databases
   
   
3. 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; 
   
   
4. 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> 
   
   
5. Rename existing models on CSE.
   
   
6. Upload each model downloaded in step 4.
   upload -u <userID> -d <directory> 
   
   
7. 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).
   
   
8. After you are happy with new models accessibility, delete original models.
   
   
9. 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)

1. Stop all development work & checkin all subsets. 
   
   
2. Take backup of both CSE databases
   
   
3. 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> 
   
   
4. 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 Encyclopaedia Server'. This option will 
   
   
1. Drop and recreate the encyclopedia tables
2. Load the Public Interface views - if desired
3. 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
4. Load the schema tables

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 Encyclopaedia Tables' & also specify a unique value for Encyclopedia ID field (ensure that ID is different to any existing CSE) 
This option will

5. Truncate existing data tables, keeping prior table properties
6. Load the schema tables.
7. Initialize the required data tables with configuration data.
   
   
4. Restart the new CSE
   
   
5. 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.
   
   
6. Using the Encyclopedia Client connect to the new CSE and add the required userIDs to it.
   
   
7. Upload each model downloaded in step 3 
   upload -u <userID> -d <directory> 
   
   
8. 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).
   
   
9. 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 Host Encyclopedia (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 
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 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.

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.