## 
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 Data Division, or processing logic for
the Procedure Division, respectively. The modifier RULDELT is used in the 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.)
Rules.
## 
Naming Conventions in Rules
RULWORK**
The **DATA DIVISION** coding for your Rule will be inserted into the LINKAGE SECTION of online MMP's, within the TWA (cont.)
area. MAGEC will generate a group item above your coding. The group item will be a Cobol level 03; therefore your *work (cont.)
fields should be Cobol level 04 and greater*.
Since your Business Rule might very well be inserted into many programs, and since several Business Rules might very (cont.)
well be inserted into any one program, you should abide by certain conventions in naming your work fields. We (cont.)
suggest:
eeeee--dddddddddd
where:
eeeee
= the Element name
--
= two dashes separate the Element name prefix from the remainder of the dataname
dddddddddd
= up to 23 characters of valid Cobol dataname
This scheme will avoid conflicts between multiple Business Rules, thanks to the Element name prefix. It will avoid (cont.)
conflicts with the datanames within the generated Element definition copybook, thanks to the two dashes. It will also (cont.)
avoid conflicts with standard datanames generated into all MMP's by MAGEC, and with datanames the programmer is likely (cont.)
to define in normal customization.
**RULPROC** and **RULDELT**
The **PROCEDURE DIVISION** coding should also conform to certain conventions in order to avoid similar conflicts as (cont.)
were described for Data Division coding. We suggest a naming scheme for paragraph names, as:
BB6nn-eeeee--pppppppppp
where:
nn
= any 2-digit sequence number
eeeee
= the 5-character Element name
--
= two dashes separate the Element name from the remainder of the procedure name
pppppppppp
= up to 17 characters of valid Cobol procedure name
## 
Conditional MAGECINC's
You will likely find many occasions to code the -MAGECINC command into your Business Rule coding. One of the obvious (cont.)
situations where -MAGECINC's will be needed is when you are doing I/O on your Procedure Division logic. You will need (cont.)
to include the Element definition copybook(s) into the Data Division in order to provide the area to read into and (cont.)
write from.
This introduces an opportunity for error. Since your Rule will likely be inserted into several MMP's, there is the (cont.)
distinct possibliity that one or more of them will already be including that same copybook, resulting in duplicate (cont.)
datanames and compiler errors. In order to avoid this error we recommend that you always make your -MAGECINC's (cont.)
"conditional", that is: code them so that they will be expanded only if they have not been expanded elsewhere in the (cont.)
same program. That is done using the -IFUNIQUE command, as:
-IFUNIQUE
**-MAGECINC member/modifier
The -IFUNIQUE command must immediately precede the -MAGECINC, as shown above. It applies to the member named in the (cont.)
-MAGECINC which immediately follows it.. You can use as many of the -IFUNIQUE and as many -MAGECINC commands in one (cont.)
Rule, or in one program, as you need.
The -IFUNIQUE works even if another -MAGECINC for the same member appears physically behind this one in the program. (cont.)
The -IFUNIQUE feature is not limited only to Business Rules, it can be used anywhere, but it is particularly useful in (cont.)
Business Rules.
## 
Restrictions in Rules
Since your Rules will be inserted into many programs you should abide by certain restrictions when coding them. This is necessary to avoid tying the Rule to one particular program or screen.
Never code references to screen fields**, except for the four standard fields which MAGEC forces all screens to include. They are:
SFUNCT function code - 6 characters
**SKEY free-form key - 31 characters
SCOMPL completion message - 40 characters
SERRMSG error message area - 240 characters
This includes all the associated attribute, color, highlighiting, position, and error flag fields for them.
You can, however, refer to screen fields indirectly using MAGEC's symbolic screen field references**.
Never code **references to datanames** except those that are either:
1) defined in the RULWORK code for this Rule.
**2) defined as standard fields in all MMP's.
3) defined in the Element copybook for the Element this Rule is associated with.
4) Cobol special registers available to all programs.
Never code references to paragraph names** except those that are either:
1) defined in this RULPROC logic.
**2) generated into all MMP's by MAGEC.
Never GO TO** paragraph names except those that are both:
1) within the BB600 through BB699 routine.
**2) defined in either every MMP, or within this RULPROC logic.
To exit **the RULPROC logic you should GO TO BB699-EXIT.
## 
Setting Default Values
SInce the RULPROC coding is inserted into the MMP as the last process before the data is actually updated to the (cont.)
database, you will find that this is a handy facility for testing for "null" values in fields and setting default (cont.)
values for them. This gives the DBA control over default values and relieves the application programmers from that (cont.)
chore. The result is more consistent handling of data across many applications.
## 
Preventing Updates
The most obvious purpose for Business Rules is to prevent data from being placed onto the database unless it passes (cont.)
stringent validation requirements. These validations can involve cross-field, or even, cross-file, comparisons. The (cont.)
RULPROC logic is inserted just before the actual database update in the generated MMP's; therefore it can set an error (cont.)
flag to cause the MMP to bypass the update and issue an error message instead. You do that by (cont.)
coding:
MOVE 'xxx' TO ERROR-NUMBER
**PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT.
where:
xxx
= the (alphanumeric) number of the error message you wish to have issued.
That is exactly how it is done in the customization editing that a programmer does for an MMP, except that s/he would (cont.)
usually also set the screen field's error flag for the screen field being edited. In the Business Rules, you are (cont.)
editing database fields, not screen fields. All of the screen data has been moved to the database before your RULPROC (cont.)
logic was invoked. You can; however, set the attributes for the four standard MAGEC screen fields, and you can make use (cont.)
of MAGEC's symbolic screen field referencing discussed later in this section.
## 
Creating "Master" Record
In some instances you might wish to automatically generate a "master record" when a "detail record" is added, if no (cont.)
master record already exists. A possible example: generate an invoice header when the first invoice line item is added, (cont.)
fill in default values into the header. Just as you can do I/O to read the master record, you can do I/O to add it if (cont.)
it does not exist. If you do add a new master record, it might also be helpful for you to alter the function code on (cont.)
the screen (SFUNCT) to the one which will display that new master record; the default logic ot the MMP's will then (cont.)
display the screen with the "data ADDED to database" message in SCOMPL, and the new function code in SFUNCT, ready for (cont.)
the operator to press ENTER to display the master record's data
or to update it.
## 
Assigning Keys
In some cases, you might wish to control the key value for new records added to a file by accessing a control file to (cont.)
obtain the next available key value. This relieves the application users from having to determine a new key and gives (cont.)
you, the DBA, control of new keys added. The new key values might be check digit'ed numbers.
The Business Rules are a handy place to accomplish the setting of the new key into the new record. You can access a (cont.)
control file, or record, by coding a standard I/O call. You can also call a subroutine, if you happen to have one which (cont.)
assigns key values.
If you had a Journal Entry file whose key was Voucher Number, you might have many different programs which could add (cont.)
new Journal Entries. Because of your Business Rule logic to assign Voucher Numbers (perhaps by calling a subroutine), (cont.)
none of the MMP's or their authors had to bother themselves with "how to assign a Voucher Number" and you are assured (cont.)
that all Voucher Numbers are assigned correctly (or, at least, uniformly).
# 

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