**
To define the Key:
 
  KYFADD VADK1
To define the two Elements:
 
  ELTADD VAD01
 
  ELTADD VAD00
To define the Data Items
 
  MAGECLBR 
(-MAGECADD DIT VAD01 operation)
To customize the Data Items:
 
  DITCHG VAD01//.....
To generate a copybook:
 
  DITGEN VAD01
To add a Business Rule and Referential Integrity checking:
 
  RULADD VAD01//RULWORK
 
  RULADD VAD01//RULPROC
 
  RULADD VAD01/RULDELT
 
# 
Executing DCLDOC
## 
Data Class Documentation
As a Database Administrator or Data Administrator you will often find a need for concise, hardcopy documentation of (cont.)
your Data Classes' definitions and Where-Used references. MAGEC provides a batch utility program which produces just (cont.)
such a report.
The report navigates through the dictionary, gathering facts related to the Data Class in question. It checks for many (cont.)
potential error conditions (inconsistent definitions or usages), missing pieces, overlapping definitions, and other (cont.)
circumstances which should be called to your attention. It also produces a where-used report showing all references to (cont.)
the Elements as primary or secondary Data Classes by both online and batch programs.
At this time, the VAD Data CLass has no references
it is not yet used by any application. Since a report of the VAC Data Class (which is used by MMP600 and MBP600B) would (cont.)
be more interesting than a report of the new VAD Data Class we just defined and created, we will produce a DCLDOC (cont.)
report for VAC. This will better demonstrate the usefulness of this report.
| ```
     DO THIS:
Execute DCLDOC using a control card of:
DCLDOC VAC
Refer to your "Offline Utilities" chapter for appropriate JCL for your particular environment.
DCLDOC is executed using the .BAT file named DCLDOCEX if you are using a PC workstation.
   
```** 
Review the output report carefully. You may wish to establish a standard of printing this report after any major (cont.)
additions or changes to the Data Class definitions and keeping the printed report on file for your use and for use by (cont.)
developers and maintenance programmers.
# 
Domains
When you were defining the Data Items (DIT's), you might recall we mentioned "Domains". We did not try to explain (cont.)
Domains at that time because we did not want to disrupt the flow of the tutorial project with a long discussion, which (cont.)
Domains certainly require. Now we will take the time to discuss them.
A Domain is a category, or class, of data items. As an example, ZIP-CODE might be the name of a Domain that you have (cont.)
defined; you might have specified that ZIP-CODE's all should be five digit numeric items with a prompt (heading) of (cont.)
"Zip:", you might also have keyed in a narrative explanation which applies to ZIP-CODE's, in (cont.)
general. 
Then you might specify that the data item named CUS01-ZIPCD is in the ZIP-CODE domain. You would do that by typing the (cont.)
Domain Name "ZIP-CODE" into the Domain Name specification on the DITxxx screen for the CUS01-ZIPCD data item. MAGEC (cont.)
will ensure that the specifications for CUS01-ZIPCD are compatible with the Domain definition; it will also default (cont.)
(copy) any specifications (i.e. Narrative, Prompt, etc.) which you have left blank. The Domain serves, therefore, as a (cont.)
model for zip code fields everywhere. You would likely have many other data items in other elements and files which are (cont.)
also in the ZIP-CODE domain. This mechanism ensures that all of them follow certain rules of conformity to one (cont.)
another.
It is not required that all data items within a Domain be defined *identically*, merely that they be compatible. For (cont.)
example, one ZIP-CODE might be packed, another binary, and another display numeric; all must be five digits and (cont.)
numeric, however. This ensures that you can use a Cobol MOVE from any one to any other without corrupting the data or (cont.)
your program. One possible exception is that it is legal for one ZIP-CODE item to be signed while another is not. You (cont.)
will receive a warning message when defining the data item telling you that a sign will potentially be lost when (cont.)
referencing this data item, but you can ignore the warning and accept the risk. This is done because signed numerics (cont.)
are often more efficiently accessed than unsigned numerics, and many people will specify signs even on items which can (cont.)
never be negative.
You may have noticed from the above explanation that a data item may be "subordinate" to both an Element and a Domain. (cont.)
Further, an Element may have several Data Items below it, and a Domain may have several Data Items below it. If you (cont.)
wished to change the rules for a given Domain, say to change ZIP-CODE from a five-digit to a nine-digit numeric, you (cont.)
would probably appreciate the ability to get a *Where-Used* report for that Domain. Fortunately MAGEC provides both (cont.)
online and hardcopy Where-Used reporting for Domains. Refer to the topic Suggestions Regarding Domains later in this (cont.)
chapter.
The diagrams in Figures 26-28 will help to clarify the relationship between the various entities.
**
NOTE:
**
Your *Programmer's Reference Guide* contains a discussion about Domains in its "Database Administration" chapter.
## 
Data Definition Entities
*
Figure 26 -- Data Entities Diagram
## 
Defining Domains
To define a Domain you use the DOMADD function. Domains are uniquely identified in the dictionary using a six-digit (cont.)
number, they also have a twenty-character name. To add a new Domain you would enter the online (cont.)
command:
**
DOMADD nnnnnn
**
where nnnnnn is the unique id number. If one already exists with that number, you will receive the usual "Duplicate" message displaying the existing Domain definition.
A Domain definition is very much like a Data Item definition, with a few exceptions:
The Domain Name is limited to twenty characters
The "Cobol level number" must always be 50 thru 65
There is no Cobol dataname.
You should always provide a Narrative description for Domains since it will be used as the default description for any (cont.)
Data Items belonging to that Domain. If, for example, you do not specify a narrative for the Data Item named (cont.)
CUS01-ZIPCD, when an operator presses the field-level help key (PF2) for a screen field which has CUS01-ZIPCD as its (cont.)
source/target, MAGEC will get the narrative from the ZIP-CODE domain definition.
When you are adding Data Item definitions you can also save some effort since MAGEC will copy most of the (cont.)
specifications from the Domain definition, if a Domain Name is specified for that Data Item. If you enter (cont.)
specifications which are different from the Domains, MAGEC will compare them for compatibility and disallow (cont.)
incompatible definitions.
## 
Domain-driven Joins
Proper use of the Domain facility of MAGEC will enable MAGEC to further automate the application development processes, specifically the logical joining of files.
Consider the situation in which you have two Data Classes (files), as:
CUS Customer data
**IVC Invoice data
Now, suppose that the key to the customer data was customer number, which was defined as a Data Item named (cont.)
"CUS01-CUSTNO". Also suppose that there is a Data Item in the invoice record named "IVC01-CUST", and that it contains (cont.)
the customer number. Further suppose that both these Data Items are defined as belonging to the Domain (cont.)
"CUSTOMER-NUMBER". MAGEC now has enough information to know that it can construct an exact key for the customer file by (cont.)
MOVE'ing IVC01-CUST to CUS01-CUSTNO; therefore, it can fully automate the logical join process when an application (cont.)
needs to access the invoice data and join customer data.
Logical joining can be done without any Domain definitions or usage; however, it involves more effort by the (cont.)
application developer to build the key used to access a file. Use of the fully automated joining via Domains also gives (cont.)
the Database Administrator better control over how data is accessed.
Figure 27 -- Join Via Domains
## 
Suggestions Regarding Domains
The process used to automatically join data can be repeated for many levels. Thus, after reading the Invoice data and (cont.)
then joining the Customer data to it, you could possibly use the ZIP code from the Customer data to join another file (cont.)
which is keyed by ZIP code, and so on. You can even concatenate data items from more than one file to build the key to (cont.)
access another file. This automatic logical join facility is potentially powerful enough to eliminate almost all manual (cont.)
coding of file accesses by programmers. It depends, however, on your properly defining and using Domain (cont.)
definitions.
We suggest that you should always try to identify and specify Domain Names for those Data Items which are part of (or (cont.)
all of) a record key. Likewise you should always try to specify (the same) Domain Names for foreign keys within your (cont.)
records. This will not only help automate application development, it will also give you excellent documentation of (cont.)
relationships between Data Classes. The Where-Used reports and screens will be much more valuable to you than if you (cont.)
haphazardly (or not at all) use Domains.
When designing new files/tables, you should give consideration to identifying Domains for as many of the new Data Items (cont.)
as possible. This will help you to ensure uniform definitions and usage. You should also try to apply those Domain (cont.)
definitions to your existing Data Items--the minimum you will gain is a knowledge of which ones are inconsistent, the (cont.)
maximum is global standardization.
The offline utility program, MAGECLBR, contains a function to report usage for any Domain Name. It also has a function (cont.)
to make any necessary alterations to all Data Items belonging to a Domain in order to make them compatible. This would (cont.)
enable you to, say, change ZIP-CODE from a 5-digit numeric to a 9-digit numeric GLOBALLY*. Obviously, Element and (cont.)
record lengths might need to be adjusted after you did this. The control cards for MAGECLBR to produce a Where-Used (cont.)
report and to globally alter definitions are, respectively:
-MAGECUSE DOM dddddddddddddddddddd
-MAGECGBL DOM dddddddddddddddddddd
 
Where ddddddddddddddddddddd is the Domain Name. The Where-Used report will note any inconsistencies without altering (cont.)
any definitions. You should use it whenever you have a question regarding any given Domain.
You can get a quick online Where-Used display for any Domain by simply displaying its definition (using DOMSEE), and (cont.)
pressing PF6. The information will not be as thorough as from the hardcopy report from MAGECLBR, but it is often (cont.)
sufficient and it is much handier to obtain.
When adding Domain definitions, remember that they are identified by a six-digit unique number, and that the numbers (cont.)
from 000001 through 000100 are reserved for "figurative constant" or "literal" Domains, which have special meaning for (cont.)
the automatic logical join process.
*MAGEC Software* has plans to implement additional features which are to be driven by these Domain definitions in future releases of MAGEC. Your input and ideas will be appreciated.
# 
Appendix A -- Deleting Definitions
## 
Restoring/Reloading MAGEC Dictionary
For a number of reasons this project, and the other turorial projects, are best done on a microcomputer, rather than on (cont.)
a mainframe. Being the sole user of the system allows you to do things which would be very un-neighborly on a (cont.)
multi-user mainframe. If you are doing this project on a PC or PS/2 using the PC version of MAGEC, you might be able to (cont.)
simply re-install part of MAGEC's dictionary to delete the VAD definitions. Using the initial installation diskettes (cont.)
you could, at the DOS prompt, enter the commands:
C:
CD\MAGEC
RESTORE A: DCLK1.DAT
RESTORE A: KYFK1.DAT
RESTORE A: ELTK1.DAT
RESTORE A: ALGK1.DAT
This assumes that your \MAGEC directory is on the C: drive and that the diskettes are on the A: drive; you may need to adjust the above for your particular situation.
## 
Un-Defining VAD Data Class
Whether you are using a PC or mainframe you can un-define the VAD Data Class. To delete all definitions for the sample VAD Data Class and all subordinate entities:
In all environments:**
Online, in MAGEC, do the following functions:
DITPUR VAD01
LBRPUR VAD01-C
RULPUR VAD01
ELTDEL VAD00
ELTDEL VAD01
KYFDEL VADK1
DCLDEL VAD
**Click here for [MAGEC Data Diagram Tool](../images/MAGEC_Data_Diagram_Tool.pdf) User Guide.
Figure 28 -- Example, Joined Via Domain
On a PC:**
*Also*, issue the following command from the DOS prompt:
ERASE C:\MAGEC\VADK1.DAT
# 
Appendix B -- DB Commands
The following is a list of DB Commands which may be used with DBDITO. For more detailed information, please refer to (cont.)
the *MAGECIO Commands* topic in the "Database Administration" chapter (section, Accessing Files from (cont.)

Next: <a href="https://magec.com/DOC/markdown/data05.md.txt">https://magec.com/DOC/markdown/data05.md.txt</a>