**RDUKY DEF** — read DEF record for update by key
**UPDAT DEF** — update DEF record
**CLSFL DEF** — close DEF
**REDKY DEF** — open DEF read-only, read record by key
***LOAD** — set default open switch to "open-for-update"
**REDKY XYZ** — open XYZ for-update, read record by key
**end of job** — close all files automatically
# Audit Stamps
## Element 00
An Audit Stamp is a 36-byte portion of a record that is used to record Who, Where, and When the record was last updated (cont.)
or added. It is an optional feature of MAGEC which may be specified for some Data Classes and not for others as needs (cont.)
dictate. If Audit Stamp support is specified for a Data Class then the Audit Stamp must be defined as a separate (cont.)
Element with a name in the format:
eee00
Where: eee = Data Class name, 00 = literal value of '00'
Whenever a program reads any Element(s) of the Data Class (with Audit Stamp specified) MAGECIO also automatically reads (cont.)
the Audit Stamp Element into the area named AUDIT-STAMP. There is no need for you to provide copybooks to define the (cont.)
Audit Stamp nor is there a need for the programs to include the Audit Stamp Element name (eee00) in the Element list. (cont.)
It is illegal for any program to update an Audit Stamp Element and MAGECIO will abort the task if such an update is (cont.)
attempted, a Return Code of 97 (Abend Code DB97) will be set. There is a standard copybook included into the Audit (cont.)
Stamp area from the MAGEC library, it is named ELT00-C and contains the definition of any Data Class's Audit Stamp. The (cont.)
definition includes:
**AS-FILE-NAME** — The Data Class name this record belongs to (3 characters long)
**AS-DATE-UPDATED** — The date (YYMMDD) this record was last updated or added (or pseudodeleted)
**AS-TIME-UPDATED** — The time (HHMMSS) this record was last updated or added (or pseudodeleted)
**AS-TERM-LAST-UPDATED** — The Device (Terminal) ID from which this record was last updated, etc. (4-char.)
**AS-OPER-LAST-UPDATED** — The initials of the operator who last updated (etc.) this record (3 char)
**AS-PROGRAM-LAST-UPDATED** — The name of the program (MMP) which last updated (etc.) this record (8 char)
**AS-EMPNO** — The Employee number of the operator who last updated (etc.) this (4-byte binary, 9-digit)
**AS-FILLER** — An unused byte reserved for future use
**AS-INACTIVE-FLAG** — A 1-byte flag that is set to HIGH-VALUE (X'FF') to indicate "pseudodeleted" by MAGECIO instead (cont.)
of actually deleting the record (if Real Delete = N on DCL file definition for this Data Class)
# File Utility
## DBDITO Function
There is a general purpose utility online Function provided with MAGEC which allows you to do any database request via (cont.)
your CRT. It permits you to see and alter any file or database available to MAGEC using an over/under (cont.)
character/hexadecimal display. It may be used to add, change, or delete as well as just look at data on the (cont.)
files.
To use this utility just enter the Function Code:
DBDITO (full function)
-or-
DBUTIL (read only)
The MAGEC security system governs who may use each of the above Functions and some additional restrictions also apply (cont.)
because of the dangerous possibilities. DBDITO and DBUTIL are fully documented via the online HELP facility, press PF1 (cont.)
after the screen is returned to you for full instructions.
Some of the many common uses for the DBDITO utility are:
Undeleting pseudodeleted records
Correcting bad data on file
Creating test data for new programs
Verifying that a file is open/available
Training the use of the MAGECIO Request & Commands
You may refer to the MAGEC "Data Definition" tutorial for additional instructions on the use of DBDITO.
# Logical Join
## Secondary Data Classes
Very often the application developers will want to produce MMP's and MBP's which access more than one Data Class. For (cont.)
instance, the MMP that is to provide inquiry and update capability for the Invoice data will also need to access the (cont.)
Customer data to display name and address, etc.
In a "flat file" or "relational" environment there are no physical "pointers" from one record to another; therefore the (cont.)
connection between records is known as a "logical connection" and the process of specifying that connection is known as (cont.)
"logically joining" the records.
In the hypothetical Invoice MMP we mentioned above, the Invoice data would be the "Primary Data Class" and the Customer (cont.)
data would be a "Secondary Data Class". There could be any number of additional Secondary Data Classes, but only one (cont.)
Primary. In order to access the Secondary Data Class the developer must know: 1) which key (if there are more than one) (cont.)
of that Data Class is to be used, and 2) how to construct the Key Value to be used. In our hypothetical example we (cont.)
might wish to use the Customer-Number key of the Customer Data Class and, as the Key Value we might use the (cont.)
Customer-Number from the Invoice record we are processing.
A Data Item in the Primary data that is used as a key to access the Secondary data is known as a "Foreign Key". (cont.)
Likewise, a Data Item from the Secondary data that is used to access yet another Secondary Data Class, is also known as (cont.)
a Foreign Key. It is also possible to concatenate Data Items, from one or more Data Classes, in order to construct the (cont.)
key to access another Data Class. It is also possible to access a Data Class by constructing only the high-order (cont.)
portion(s) of the key and using a generic access, known as a "Partial Key Join". This would be appropriate if you were (cont.)
using the Customer file as your Primary data and joining to the Invoice file, where ther may be many invoices for a (cont.)
given customer.
Specification of Logical Joining rules is done by developers as a part of the normal development process. In the (cont.)
Semi-Automatic development sequence the developer will be prompted for all the necessary information and all the needed (cont.)
coding will be generated for him. Alternatively he may manually do the coding using the Customization insertion points (cont.)
named %JOIN and %DATADEF.
In the Fully-Automatic development process MAGEC will generate the Logical Join coding with no help from the developer (cont.)
other than to select which Data Classes he/she wishes to have joined. This relies upon the definition of Domains for (cont.)
Data Items that are keys, components of keys, or foreign keys. The Domain definitions enable MAGEC to match-up foreign (cont.)
keys with primary key fields of those Data Classes to which a join is possible. For example, if the Customer-Number (cont.)
field in the Invoice record is defined as belonging to the same Domain as the Customer-Number field of the Customer (cont.)
record, and that field is also the key to the Customer file, then MAGEC knows that it can use the Invoice's (cont.)
Customer-Number to access the Customer file.
Thus, the developer has three levels of automation to choose from to generate Logical Joins:
1) manual--do it using Cobol coding him/herself
2) semi-automated--let MAGEC do most of the work
3) fully-automated--let MAGEC do it all
# Table Maintenance
## TOCxxx Functions
MAGEC's Automatic Table Lookup Editing feature is used by both your application developers' generated MMP's and by the (cont.)
MAGEC System MMP's as well. The Lookup Table feature supports up to 999 Tables that are identified by their Table (cont.)
Numbers (001 thru 999). MAGEC reserves the use of Table # 200 thru 255 for "system use". Therefore, you may define up (cont.)
to 744 of your own Tables for your applications.
Each Table is defined by an entry in the "Table of Contents" (TOC). To list the TOC entries enter:
TOCLOC 1
To add a new Table to the system enter:
TOCADD ttt
where:
**ttt** — = new Table number
The screen will return to you asking for a DESCRIPTION and an ERROR NUMBER. The description is free-form. The Error (cont.)
Number must be defined on the MAGEC Error file (ERR). It is the Error Number which will be displayed to the application (cont.)
user when he/she mis-enters into a screen field that is being validated against this Table.
We recommend that you use Error Numbers which correspond to the Table Number for which it applies. For example, Error (cont.)
Number 001 for Table 001. However, remember that MAGEC reserves Error Numbers starting with a '9' for its own (cont.)
use.
## TBLxxx Functions
To list the entries (codes and descriptions) which make up any given Table, enter:
TBLLST ttt
where:
**ttt** — = Table Number
To add a new entry to a given Table enter:
TBLADD ttt/ccccccc
where:
**ttt** — = Table Number
**ccccccc** — = the new Code (16 char. max.)
You may similarly change the description for an entry using TBLCHG, or delete an entry entirely using TBLDEL.. You can (cont.)
only display or add to a table number which has been defined via the TOCADD function described (cont.)
above.
The changes you make to the Tables take effect immediately and do not require you to use the **LOAD Function or to (cont.)
recompile any program. Naturally, the MAGEC Security System governs access to the Table and Table of Contents (cont.)
Functions.
## Where-Used for Tables
Table Lookup validations are automatically done by MAGEC's reusable routines. They are triggered by the specifications (cont.)
made for screen fields. In many cases it would be useful to know every reference to a given table; e.g. every screen (cont.)
field that is validated against that table. This is especially important when grand changes are planned for that table (cont.)
and you would like to determine the impact of those changes.
To find every reference to a table you would use the online command:
SCDTBL nnn
where
**nnn** — = the table number in question
You will receive a list of all screen fields which reference that table. If you press PF13, the list will be "spooled" for hardcopy printing.
## Field-level HELP for Table-edited Fields
MAGEC's Field-level HELP facility is especially useful for screen fields that are validated against a table. If the (cont.)
operator presses the PF2 key with the cursor pointing to such a field on the screen, MAGEC will display the usual (cont.)
one-screen help text for that field plus a message saying that he/she can press PF8 to list the table's (cont.)
entries.
If the operator presses PF8 to begin scrolling through the entries of the table, he/she can then use the list on the (cont.)
screen as a "pick list" by pointing with the cursor to a desired value and pressing ENTER. MAGEC will return to the (cont.)
application screen with the selected value filled into the screen field.
# Initializing Files
## MAGINIT
Defining a new file to MAGEC consists of doing the DCL, KYF, and ELT definitions described in this chapter. Creating (cont.)
the file in a mainframe environment consists of executing whatever utility (AMSERV, IDCAMS, DDCFMNT, etc.) is (cont.)
appropriate for the type of file. Initilizing the file is merely a process of opening, writing to, and closing it. This (cont.)
can be done using various utilities provided with the access method or database management system; for mainframe VSAM (cont.)
files and for PC MAGEC files initializing can also be done using a special utility named MAGINIT. In the PC MAGEC (cont.)
environment MAGINIT does the functions of both creating and initializing the file in one step. To execute (cont.)
MAGINIT:
MVS MAGINIT JCL
//MAGINIT JOB (acct...)
//MAGINIT EXEC PGM=MAGINIT
//STEPLIB DD DSN=MAGEC.LOADLIB,DISP=SHR
//NEWFILE DD ... DSN for the VSAM file to be initialized ...
//
DOS MAGINIT JCL
// JOB MAGINIT
// DLBL NEWFILE.'...VSAM file to be initialized..',,VSAM
// EXEC MAGINIT
PC MAGEC MAGINIT command
C:> MAGINIT yyy
where:
**yyy** — = Data Class
You will be asked for the name of the Data Class to be initialized if you fail to provide it in your "command".
**Note:** With MAGEC on the PC or PS/2 you also have the MAGLOAD and MAGUNLD commands that are useful. They are described in the Installation Guide.
# Business Rules
## What is a Business Rule?
A Business Rule is a routine that is triggered (invoked) whenever an MMP updates or adds data to the database for a (cont.)
specified Element. It consists of Cobol coding that is automatically inserted into the generated MMP by MAGEC. Business (cont.)
Rules are normally coded by the Database Administrators (DBA's), rather than application programmers. This gives the (cont.)
DBA's a much higher level of control over enforcing the integrity of the database and the data that is in the database. (cont.)
It also reduces the work of the application developers since they no longer need to concern themselves with any of the (cont.)
validation, editing, and default valuing that is done by the Business Rules. Since any given Element might be updated (cont.)
by several MMP's, this scheme also eliminates much redundant effort.
Business Rules can include almost any type of processing, including calling subroutines and doing I/O. They can (cont.)
accomplish complex cross-field or cross-file validations, they can update other files and they can alter the data in (cont.)
the Element before it is updated to the database.
## Defining Business Rules
Business Rules are actually special library members on the MAGEC source library, the ALG file. You maintain them in (cont.)
much the same way that you maintain any other member, except that you use a special set of online functions designed (cont.)
specifically for Business Rules. They operate similarly to the functions used for ordinary members.
Whereas you maintain ordinary members using the functions:
LBRADD LBRSEE LBRLOC etc.
For Business Rules you use the functions:
RULADD RULSEE RULLOC etc.
Whereas the key format for ordinary members is:
nnnnnnnn/mmmmmmmm
where:
**nnnnnnnn** — = 8-character member name
**mmmmmmmm** — = 8-character modifier (optional)
For Business Rules the key format is the same, except:
1) The member name is always the 5-character Element name.
2) The modifier is always either: RULWORK or RULPROC, to designate that the member is work field definitions for the (cont.)
Data Division, or processing logic for the Procedure Division, respectively. The modifier RULDELT is used in the (cont.)
Deletion Rules facility described later in this chapter.
Hence, to add both Data Division and Procedure Division code as a Business Rule for the Element named CUS01, you would use the commands:
RULADD CUS01/RULWORK (for Data Division) RULADD CUS01/RULPROC (for Procedure Division)
The online text editor works just like it does for ordinary library members. You could refer to the "MAGEC Librarian" (cont.)
chapter for more detailed descriptions about the source online librarian. You could also refer to the MAGEC "Data (cont.)
Definition" tutorial to review actual screen examples for the entire data definition process, including Business (cont.)

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