- 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.
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)
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';
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:
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.
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
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)
Option 2 (remove original models from CSE prior to reload)
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
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.