---
title: "data_main"
original_file: "data_main"
generated: "2026-06-12 10:24:14"
---
**
#
Introduction### Database Administration Tutorial
##
Who Should Read This Guide
This tutorial is written primarily for use by those persons who will be using the MAGEC software to develop and (cont.)
maintain applications or to define (and maintain definitions of) files and databases to the (cont.)
dictionary.
Copies of this tutorial should be distributed to:
Application Developers
Database Administrators
System Programmers
Auditors
This chapter will teach you how to define data to the MAGEC Dictionary. To demonstrate the process most effectively, it (cont.)
uses a sample project based upon defining data similar to that used by the VAC system referenced in the MAGEC (cont.)
"Application Developer" tutorial.
##
Supplemental Reading
This tutorial is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you (cont.)
understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of (cont.)
MAGEC. We suggest that you first read the MAGEC *Application User's Guide*, if you have not already.
This chapter has a tutorial format which guides you through the definition of an actual sample file. You might also (cont.)
wish to refer to other sections of the MAGEC *Programmer's Reference Guide* for more information relating to data (cont.)
definition, specifically:
"Database Administration"
"Security System"
"Offline Utilities"
These are not required reading, but they will help you to gain a more complete understanding of the MAGEC environment.
##
How to Use this Tutorial
In this tutorial you will notice that there are many screen exhibits showing, step by step, exactly how each screen (cont.)
should look as you go through the exercise. You will also notice, preceding each exhibit, both descriptive explanations (cont.)
and concise commands. The commands tell you exactly what to do to accomplish the project. The rest of the text gives (cont.)
you a more complete understanding of what you are doing, and why, and how to get more information.
You may want to first go through this chapter following the tutorial exercise, doing the project as you go, skimming (cont.)
over the background explanations. Then you might re-read the chapter more slowly and completely to get greater (cont.)
understanding. This approach has proven very effective for many people.
In order to help you to discern the commands from the background as readily as possible, you will notice that they are enclosed in a box.
| ```
DO THIS:
Commands look like this.
```**
#
Scope of Project
In this project you will define a new "file" to the MAGEC Dictionary. Actually, you will define a "dummy" which is (cont.)
modelled after the VAC Data Class used in the other tutorial projects. The purpose for this project is to teach you the (cont.)
steps necessary to define your own files to the Dictionary. This project should be done, or at least reviewed, by all (cont.)
Database Administrators and by all Application Developers. The Data Class you will define is the "VAD" (Vacation (cont.)
Dummy). The actual file name will be:
\MAGEC\VADK1.DAT (for PC MAGEC with Realia COBOL)
"MAGEC.VAD.CLUSTER" (for mainframe VSAM -- DD/DLBL Name = VADK1)
The file has one key (VADK1) which is the Employee number (9 digits) followed by nine bytes of blank padding
a total of 18 bytes long. The file has two Elements, (VAD00 and VAD01). Element VAD00 is the 36-byte Audit Stamp, Element VAD01 is the actual data portion of the record.
If you are doing this project on a mainframe you may not wish to actually follow through with the execution of IDCAMS (cont.)
and so forth. On the PC, however, it is very simple to create the file using the MAGEC utility "MAGINIT", and then (cont.)
later to delete it using the DOS command "ERASE".
The procedure you will follow to define (and create) the new Data Class is:
1. Use DCLADD to define the Data Class.
2. Use KYFADD to define the Key.
3. Use ELTADD to define the Element(s).
4. Use MAGECLBR to define the Data Items (fields).
5. Use DITCHG to further tailor the Data Item definitions.
6. Use DITGEN to generate a standard COBOL definition.
7. Use MAGINIT to create and initialize the file (on PC)
** or, use IDCAMS to create the file (on mainframe), then use MAGINIT to initialize it.
8. Use DBDITO to test the new file (if you did step 7).
NOTE:
**
If this project has already been done by another student, you must first "undo" it before you can begin. To "undo" the project refer to Appendix A of this tutorial.
#
Define Data Class
##
DCLADD
To begin, you must define the new Data Class to the MAGEC Dictionary.
| ```
** DO THIS:
Log on to MAGEC using: ID = 18, Password = ALEE.
```**
| ```
** DO THIS:
Key the command: DCLADD VAD and press ENTER.
```**
Your screen should look like the one shown here.
The Data Class definition gives MAGEC high-level specfications for the new file.
**Data Class **will be filled in by MAGEC, you do not enter anything into it.
**Description** is a 30-character free-form text field.
**Critical File (Y or N)** is yes or no specification as to whether this file is one of MAGEC's critical files. (cont.)
Specifying Y here will cause MAGEC to give this file priority when loading specifications into its in-memory tables in (cont.)
the event of a shortage of space. Your data files should almost always have N specified here, therefore, this parameter (cont.)
defaults to N.
**Recording Mode** may be F or V (fixed or variable).
**Max Record Length** may be up to 32,767.
**Audit-Stamp** specifies whether or not this file is to have a 36-byte portion (Element) of the record reserved for (cont.)
MAGEC to stamp "who", "when", and "where" this record was last updated (or added or deleted).
**Real Delete** specifies whether deletes to this file are to actually delete the record. If you specify N then the (cont.)
records will simply be flagged for deletion (pseudodeleted). The deletion flag is within the 36-byte Audit Stamp; (cont.)
therefore, you cannot specify N for Real Delete unless you have specified Y for Audit Stamp.
**Data Base ID** is for use only with Datacom/DB files, it should be 000 for all others.
**Block Size** is the physical block or control interval size.
**Access Method** specifies the type of file; for example: SQL, VSAM, DLI, or Datacom, etc.
**Gateway Name **specifies the name of the Gateway machine (as defined on MAGEC Lookup Table #248) which controls this (cont.)
Data Class. If MAGEC's TCP/IP networking facility is not installed this specification should always be left blank or (cont.)
set to "LOCAL". If a valid Gateway Name (from Table #248) is specified, MAGEC's I/O module will automatically pass any (cont.)
requests to read or write to this Data Class to the specified Gaterway machine. The results will be passed (cont.)
back.
| ```
**
DCLADD VAD Enter data to be ADDED
M A G E C Data-Class Definition
Data Dictionary Maintenance
Data-Class=
Description: __________________________
Critical File (Y or N): N
Test Prod
Recording Mode: _ _
Max Record Length: _____ _____
Audit-Stamp (Y or N): _ _
Real Delete (Y or N): _ _
Data Base ID: ___ ___
Block (CI) Size: _____ _____
Access Method: _______ _______
Gateway Name: ________________ ________________
```**
Figure 01 -- Data Class Definition Screen
The Data Class definition contains high-level information about the new file. You can refer to the Database (cont.)
Administration chapter of your MAGEC manual for detailed descriptions of each field on this screen.
| ```
** DO THIS:
Key in the specs as shown below, press ENTER.
```**
If you have made any errors you will receive error messages and you can press the HELP key (PF1 on mainframe, or F1 on (cont.)
PC) for further assistance. Once you have corrected any errors your new DCL definition will be recorded and you will be (cont.)
transferred immediately to the Key Definition Screen.
If you are doing this project on a PC, you will still specify VSAM as the Access Method since MAGEC provides (cont.)
transparency, allowing you to treat indexed files on the PC exactly as if they were mainframe VSAM (cont.)
files.
| ```
**
DCLADD VAD Enter data to be ADDED
M A G E C Data-Class Definition
Data Dictionary Maintenance
Data-Class=
Description: MAGEC Vacation Dummy file_____
Critical File (Y or N): N
Test Prod
Recording Mode: F F
Max Record Length: 270__ 270__
Audit-Stamp (Y or N): Y Y
Real Delete (Y or N): N N
Data Base ID: 0__ 0__
Block (CI) Size: 540__ 540__
Access Method: VSAM ___ VSAM___
Gateway Name: ________________ ________________
```**
Figure 02 -- Data Class Definition Screen
#
Key Definition
##
KYFADD
The Key Definition Screen looks like the figure shown below.
After you have successfully added the new DCL definition (from prior page), you will automatically be presented the Key (cont.)
Definition Screen, as shown in Figure 03. It is prepared for you to immediately enter the specifications for the VADK1 (cont.)
key, the primary key for the VAD Data Class.
If your new file has alternate keys (subordinate keys), you may need to also define them. The "K1" suffix means that (cont.)
this key is the *primary** key (also called **Master key)*. Alternate keys may be defined using suffixes of "K2" (cont.)
through "K9". If more than nine keys are needed you may define the rest using alphabetic "key numbers" (i.e. xxxKA thru (cont.)
xxxKZ); however, that would be very unusual and would require you to do some minor customization when you use this Data (cont.)
Class as the primary Data Class in applications.
The key may be subdivided into as many as five component fields. This allows your key field to be a group item which is (cont.)
broken down into elementary items. Each of the elementary (Component) fields can have its own set of attributes (max, (cont.)
min, type) to tell MAGEC how to normalize (edit and reformat) an operator's entry in order to construct the proper key (cont.)
for accessing the file. Every valid Cobol data representation is supported, as evidenced by the Field Type codes shown (cont.)
on the screen.
A detailed definition of each field on this screen is included in the "Database Administration" chapter of your MAGEC manual.
| ```
** DO THIS:
Continue to the Figure below..
```**
**
NOTE:
next: data02.md.txt