applications which have a given table number specifed as the lookup table for a screen field. The command (cont.)
is:
SCDTBL nnn
where:
**nnn** — = the desired table number (001 through 255)
In order to limit online overhead the search is subjected to the standard "scan limit" or 1000 I/O's before it is interrupted. You can press ENTER to continue the search; however, if you wish.
## DCLDOC
A special batch utility program is provided (MAGEC version 2.1 and later) to produce complete documentation for a Data (cont.)
Class, including where-used reporting. The DCLDOC program accepts a control card (multiple control cards are permitted) (cont.)
specifying the 3-character name of the Data Class for which you wish documentation printed. It reports on all Keys, (cont.)
Elements, Data Items, Business Rules, and references. The where-used reference report shows both primary and joined (cont.)
references for both online MMP's and batch MBP's.
To invoke the report, execute DCLDOC with a control card as:
DCLDOC xxx
where:
**xxx** — =a Data Class name in columns 8-10 of the control card
If you wish to have all lowercase alphabetics in the printed oputput converted to uppercase, use a control card as:
DCLDOC xxx U
where:
**U** — = literal "U" in column 12, a "Y" is equivalent to "U".
## Business Rules
When you are entering or maintaining Business Rules online it is often useful to be able to see a where-used report to (cont.)
indicate which programs will be affected (need to be recompiled) if you alter this rule. From any of the RULxxx or (cont.)
ELTxxx functions' screens you can press PF6 to request such a report. The results wil be displayed to you online. You (cont.)
could also enter the command:
RULUSE eeeee
where:
**eeeee** — = the desired element name
## Domains Global Changes
An offline facility is provided to help you to make global changes based upon Domain definitions. This enables you, for (cont.)
example, to change all zip codes from five digits to nine digits. That assumes, of course, that all zip code fields in (cont.)
all files are defined as belonging to the same Domain.
To make such a global change you would first alter the definition of the Domain. This is done online using the DOMCHG (cont.)
function. Next you should run a where-used report to give yourself documentation of all references that are going to be (cont.)
altered. *You may skip this step at your own peril!* The global change operation will also produce a report of what was (cont.)
changed, but you might prefer to know what will be changed beforehand, then compare it to the report produced (cont.)
after-the-fact.
Finally you would execute the global change operation. To do so you would execute the MAGECLBR batch utility using a control card of:
-MAGECGBL DOM dddddddddddddddddddd
**where:**
**dddddddddddddddddddd** — = the desired Domain name
This operation will alter the Data Item definitions for all fields affected. It will not alter any Element, Data Class, (cont.)
Key, or file definition (i.e. IDCAMS) parameters. It is up to you to make any needed changes to record lengths, key (cont.)
lengths, element lengths, or displacements. It may also be necessary to unload, reformat, and reload the data from the (cont.)
files. The reports produced should provide you with a checklist of modified Data Items and Elements
the rest is up to you.
# File Reorganization
MAGEC's dictionary files are simple VSAM KSDS (on the mainframe) or standard indexed files (on the PC). They are single (cont.)
key files (no alternate indices). They should be occasionally backed up and reorganized to maintain optimum (cont.)
performance. The method used to reorganize these files is no different from the method used to reorganize other such (cont.)
files in your environment. MAGEC provides some assistance in the form of pre-coded IDCAMS (or AMSERV) control cards (on (cont.)
the mainframe) and a .BAT file (on the PC).
## Mainframe
There are three members on the MAGEC library (ALG file) which will help you to reorganize the dictionary VSAM files. They are:
IDCAMBKP/REPRO IDCAMRST/REPRO DEFFILES/VSAM
The procedure for reorganizing and backing up the files involves:
1) backup to tape using the IDCAMBKP/REPRO control cards,
2) deleting and redefining the files to the VSAM catalogue using the DEFFILES/VSAM control cards, and
3) reloading the files using the IDCAMRST/REPRO control cards with the tape from step 1 as input.
The control cards provided are merely samples. You may wish to customize them for your particular environment. In the (cont.)
backup and restore control cards you will notice the NOREWIND parameter specified. The MVS version of IDCAMS does not (cont.)
support that option, so you will want to remove it if you are an MVS installation.
## PC
The PC (simulated) VSAM files can be reorganized using a .BAT or .CMD file provided with MAGEC. It is necessary to have (cont.)
enough disk space available on your hard disk drive to hold another copy of the file being reorganized since the (cont.)
process involves copying the file to a new, reorganized file and then erasing the old one and renaming the new one to (cont.)
the proper name. All simulated VSAM files in MAGEC have an extension of .DAT (for your information). The .BAT file is (cont.)
named: REORG.BAT and is in the \MAGMF\JCL directory. To invoke it, at the DOS prompt enter the (cont.)
command:
REORG xxx
where:
**xxx** — = the Data Class name to be reorganized)
Although this procedure is generally very safe, it is smart to first backup your hard disk to tape (or other medium) before doing any reorganizations.
## TWA File Purge
The TWA file is used by all online transactions as a place to store data to be passed from transaction to transaction (cont.)
and from program to program. There are several different types of records stored on the file for various purposes. Some (cont.)
of them are simply to provide pseudo-conversational processing for all transactions without imposing the need for the (cont.)
programmer to handle the saving of passed data and so forth. Other types of records are used by the online help (cont.)
facility, window swapping, and other integral features of MAGEC.
The records on the TWA file have various different keys that identify what they are for; however, in all cases the keys (cont.)
are eight characters long and begin with the four-character terminal ID that makes the keys unique. This scheme also (cont.)
gathers all records for a given terminal in physical proximity to one another.
*Regular reorganizations of the TWA file are highly recommended.*
All of the records on the TWA file are dynamically created (added) whenever they are first needed, then they are reused (cont.)
(updated) as they are subsequently needed. For example, online documentation records will be created the first time (cont.)
that online documentation is used at a given terminal, then merely updated as online documentation is subsequently used (cont.)
at that terminal.
This scheme works well and reduces overhead significantly; however, it has one drawback. The TWA file can become (cont.)
over-populated with records for terminals that are no longer active. There are three good methods for solving this (cont.)
problem.
*First*. You can totally purge the TWA file and re-initialize it. This lets MAGEC dynamically re-add any needed records (cont.)
as the need for them arises. The adding of records is less efficient than updating in place, but the penalty is usually (cont.)
small and this method is a sure-fire way to solve the over-population problem.
To do this you should execute the IDCAMS DELETE/DEFINE, then execute MAGINIT to initialize the file. This could even be done in the online startup JCL, if desired.
*Second*. You can selectively purge the records for inactive (or any other) terminals via an online function. The command to do so is:
TWAPUR tttt
where tttt is the desired terminal ID. If you omit the terminal ID, all records for all terminals (except for the (cont.)
terminal where you are) will be purged (deleted). If you subsequently (after the online system is down, or the TWA file (cont.)
closed to it) reorganize the file, performance will benefit greatly.
*Third*. You can automatically selectively purge records from the file that seem to be inactive (have not been used in (cont.)
thirty days or more) by executing the TWAUTIL batch utility program. Following that up with a reorganization is not (cont.)
mandatory, but it is a good idea since it will improve online performance. Active records will remain on file and not (cont.)
need to be re-created. Since TWAUTIL also "cleans up" some other types of conditions on the TWA file, some users (cont.)
execute it in either the TP monitor (e.g. CICS) startup or shut down procedure.
Be sure that CICS is down before running TWAUTIL. If CICS is up a SOC1 will result. TWAUTIL performs the following functions:
Deletes TWA records that are more than 30 days old
Deletes CUTB, USR, DOC, and POP records
Deletes SPLR if no terminal references
Deletes any other TWA records not in the following format:
Term ID valid terminal ID
Split Code 0 or W
User-view 1 thru 8
User-modes T or P
REC-NUMBERS 1 thru 4
**OS**
```
//U2MSI1TX JOB (MSI),TWAUTIL,CLASS=M,MSGCLASS=X,
// MSGLEVEL=(1,1),NOTIFY=U2MSI2,REGION=4M
//TWADELET EXEC PGM=TWAUTIL,REGION=4096K
//* STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
//STEPLIB DD DSN=MAGEC.LOADLB74,DISP=SHR
// DD DSN=MAGEC.LOADLIB,DISP=SHR
//ALGK1 DD DSN=MAGEC.ALG.CLUSTER,DISP=SHR,
// AMP=('BUFND=11,BUFNI=3,STRNO=1')
//DCLK1 DD DSN=MAGEC.DCL.CLUSTER,DISP=SHR
//DITK1 DD DSN=MAGEC.DIT.CLUSTER,DISP=SHR,
// AMP=('BUFND=11,BUFNI=3,STRNO=1')
//DOCK1 DD DSN=MAGEC.DOC.CLUSTER,DISP=SHR
//ELTK1 DD DSN=MAGEC.ELT.CLUSTER,DISP=SHR
//ERRK1 DD DSN=MAGEC.ERR.CLUSTER,DISP=SHR
//FCDK1 DD DSN=MAGEC.FCD.CLUSTER,DISP=SHR
//KYFK1 DD DSN=MAGEC.KYF.CLUSTER,DISP=SHR
//LAPK1 DD DSN=MAGEC.LAP.CLUSTER,DISP=SHR
//MMPK1 DD DSN=MAGEC.MMP.CLUSTER,DISP=SHR
//PRMK1 DD DSN=MAGEC.PRM.CLUSTER,DISP=SHR
//REFK1 DD DSN=MAGEC.REF.CLUSTER,DISP=SHR
//SCFK1 DD DSN=MAGEC.SCF.CLUSTER,DISP=SHR
//SHDK1 DD DSN=MAGEC.SHD.CLUSTER,DISP=SHR
//SIFK1 DD DSN=MAGEC.SIF.CLUSTER,DISP=SHR
//TBLK1 DD DSN=MAGEC.TBL.CLUSTER,DISP=SHR
//TWAK1 DD DSN=MAGEC.TWA.CLUSTER,DISP=SHR
//DVCK1 DD DSN=MAGEC.DVC.CLUSTER,DISP=SHR
//SYS005 DD DUMMY,DCB=(LRECL=80,BLKSIZE=80,RECFM=FB)
//SYS007 DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
```
**PC**
```
c:
CD\MAGEC
SET SYS006=TWAUTIL.RDR[N]
SET SYS007=CON[N]
TWAUTIL
RE_SET
```
If you are using MAGEC on a PC or LAN (using MicroFocus Cobol), and if the TWA file is located on your local disk dirve (cont.)
(as opposed to a LAN server drive), then you can simply delete the TWA file and its index at any time that you are not (cont.)
actually executing MAGEC. To do this, type:
ERASE TWAK1.*
at the prompt.
MAGEC will automatically create a new TWA file when it is needed. This is an effective way to eliminate wasted space (cont.)
and cluttered indices. You can also do this same thing if the TWA file is being shared on a LAN server drive if you (cont.)
first determine that all users are off the system when you do it.
# Domain Definition
## What is a Domain?
A Domain is a global data definition that is not associated with any particular Data Class (file) or Element; rather, (cont.)
it is used as a model for the Data Item definitions (DIT's) within many Elements throughout your systems. A Domain is (cont.)
not itself a Data Item, though its definition very strongly resembles the definition of a Data Item, but it can be used (cont.)
to enforce standardized definition of Data Items. As an example: you could define a Domain named "ZIP-CODE" (cont.)
thatspecifies five (5) digits numeric and includes a descriptive narrative thatexplains what a zip code is. Then, in (cont.)
all your Data Item (DIT) definition for a field that is a zip code you could specify "ZIP-CODE" in the Domain Name (cont.)
parameter. This would indicate that each of these fields belongs to the Domain named ZIP-CODE.
MAGEC will verify that each of the Data Items belonging to ZIP-CODE has a definition compatible with the Domain's (cont.)
definition, e.g.: five-digit numeric. This helps you to ensure uniform definitions for similar data, in this example: (cont.)
zip codes.
When you are adding new definitions for Data Items that are to belong to an existing Domain, MAGEC can save you some (cont.)
effort. If you fill in the Domain Name and leave all or some of the other specifications on the DITADD screen blank, (cont.)
MAGEC will fill them in automatically from the Domain definition. Refer to the topic *DIT Entry Formats* earlier in (cont.)
this section.
If you need to know how many, and which, Data Items belong to any given Domain, you can use the where-used facilities (cont.)
of MAGEC to provide either an online display or a batch report listing all Data Items belonging to any particular (cont.)
Domain. If you wish to alter the definitions of all Data Items belonging to a given Domain, that can be done (cont.)
automatically using MAGEC's batch Global Change facility for Domains. Refer to the section, Where-Used Reporting, and (cont.)
the section, Domains-Global Changes, earlier in this chapter.
Using the Domain definitions, MAGEC can fully automate the logical joining of data from multiple Data Classes (files), (cont.)
eliminating the need for the application developer to do any coding at all when developing multi-file accessing (cont.)
applications. Refer to the section, Logical Join, earlier in this chapter. This does not mean that the developer cannot (cont.)
code logic to access other files if he/she wishes.
Domains can help you to save time in documenting your data definitions. If you provide a narrative description with (cont.)
your Domain definition, that description will automatically be applied to any Data Items thatbelong to that Domain if (cont.)
the narrative description for that Data Item is left blank. This means that for field-level help, if the narrative for (cont.)
the source/target field has been left blank, and if it belongs to a Domain, MAGEC will automatically display the (cont.)
Domain's narrative on the screen.
**Note:** The Tutorials manual contains further explanation regarding Domains in the "Data Definition" chapter under the section, Domains.
## DOMxxx Functions
To add or maintain Domain definitions, use the DOMxxx functions. The screen and functions are very similar to the (cont.)
DITxxx functions and screen. Only the differences will be described in this topic since you can refer to the discussion (cont.)
for the *DITxxx Functions* earlier in this chapter.

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