DOS MAGINIT JCL<br />// JOB MAGINIT<br />// DLBL NEWFILE.'...VSAM file to be initialized..',,VSAM<br />// EXEC MAGINIT<br />PC MAGEC MAGINIT command<br />C:> MAGINIT yyy<br />where:<br />yyy<br />= Data Class<br />You will be asked for the name of the Data Class to be initialized if you fail to provide it in your "command".<br />NOTE:<br />**<br />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*.<br /># <br />Business Rules<br />## <br />What is a Business Rule?<br />A Business Rule is a routine that is triggered (invoked) whenever an MMP updates or adds data to the database for a (cont.)<br />specified Element. It consists of Cobol coding that is automatically inserted into the generated MMP by MAGEC. Business (cont.)<br />Rules are normally coded by the Database Administrators (DBA's), rather than application programmers. This gives the (cont.)<br />DBA's a much higher level of control over enforcing the integrity of the database and the data that is in the database. (cont.)<br />It also reduces the work of the application developers since they no longer need to concern themselves with any of the (cont.)<br />validation, editing, and default valuing that is done by the Business Rules. Since any given Element might be updated (cont.)<br />by several MMP's, this scheme also eliminates much redundant effort.<br />Business Rules can include almost any type of processing, including calling subroutines and doing I/O. They can (cont.)<br />accomplish complex cross-field or cross-file validations, they can update other files and they can alter the data in (cont.)<br />the Element before it is updated to the database.<br />## <br />Defining Business Rules<br />Business Rules are actually special library members on the MAGEC source library, the ALG file. You maintain them in (cont.)<br />much the same way that you maintain any other member, except that you use a special set of online functions designed (cont.)<br />specifically for Business Rules. They operate similarly to the functions used for ordinary members.<br />Whereas you maintain ordinary members using the functions:<br />LBRADD<br />**LBRSEE<br />LBRLOC<br />etc.<br />For Business Rules you use the functions:<br />RULADD<br />RULSEE<br />RULLOC<br />etc.<br />Whereas the key format for ordinary members is:<br />nnnnnnnn/mmmmmmmm<br />where:<br />nnnnnnnn<br />= 8-character member name<br />mmmmmmmm<br />= 8-character modifier (optional)<br />For Business Rules the key format is the same, except:<br />1) The member name is always the 5-character Element name.<br />2) The modifier is always either: RULWORK or RULPROC, to designate that the<br />member is work field definitions for the Data Division, or processing logic for<br />the Procedure Division, respectively. The modifier RULDELT is used in the Deletion<br />Rules facility described later in this chapter.<br />Hence, to add both Data Division and Procedure Division code as a Business Rule for the Element named CUS01, you would use the commands:<br />RULADD CUS01/RULWORK <br />(for Data Division)<br />RULADD CUS01/RULPROC <br />(for Procedure Division)<br />The online text editor works just like it does for ordinary library members. You could refer to the "MAGEC Librarian" (cont.)<br />chapter for more detailed descriptions about the source online librarian. You could also refer to the MAGEC "Data (cont.)<br />Definition" tutorial to review actual screen examples for the entire data definition process, including Business (cont.)<br />Rules.<br />## <br />Naming Conventions in Rules<br />RULWORK**<br />The **DATA DIVISION** coding for your Rule will be inserted into the LINKAGE SECTION of online MMP's, within the TWA (cont.)<br />area. MAGEC will generate a group item above your coding. The group item will be a Cobol level 03; therefore your *work (cont.)<br />fields should be Cobol level 04 and greater*.<br />Since your Business Rule might very well be inserted into many programs, and since several Business Rules might very (cont.)<br />well be inserted into any one program, you should abide by certain conventions in naming your work fields. We (cont.)<br />suggest:<br />eeeee--dddddddddd<br />where:<br />eeeee<br />= the Element name<br />--<br />= two dashes separate the Element name prefix from the remainder of the dataname<br />dddddddddd<br />= up to 23 characters of valid Cobol dataname<br />This scheme will avoid conflicts between multiple Business Rules, thanks to the Element name prefix. It will avoid (cont.)<br />conflicts with the datanames within the generated Element definition copybook, thanks to the two dashes. It will also (cont.)<br />avoid conflicts with standard datanames generated into all MMP's by MAGEC, and with datanames the programmer is likely (cont.)<br />to define in normal customization.<br />**RULPROC** and **RULDELT**<br />The **PROCEDURE DIVISION** coding should also conform to certain conventions in order to avoid similar conflicts as (cont.)<br />were described for Data Division coding. We suggest a naming scheme for paragraph names, as:<br />BB6nn-eeeee--pppppppppp<br />where:<br />nn<br />= any 2-digit sequence number<br />eeeee<br />= the 5-character Element name<br />--<br />= two dashes separate the Element name from the remainder of the procedure name<br />pppppppppp<br />= up to 17 characters of valid Cobol procedure name<br />## <br />Conditional MAGECINC's<br />You will likely find many occasions to code the -MAGECINC command into your Business Rule coding. One of the obvious (cont.)<br />situations where -MAGECINC's will be needed is when you are doing I/O on your Procedure Division logic. You will need (cont.)<br />to include the Element definition copybook(s) into the Data Division in order to provide the area to read into and (cont.)<br />write from.<br />This introduces an opportunity for error. Since your Rule will likely be inserted into several MMP's, there is the (cont.)<br />distinct possibliity that one or more of them will already be including that same copybook, resulting in duplicate (cont.)<br />datanames and compiler errors. In order to avoid this error we recommend that you always make your -MAGECINC's (cont.)<br />"conditional", that is: code them so that they will be expanded only if they have not been expanded elsewhere in the (cont.)<br />same program. That is done using the -IFUNIQUE command, as:<br />-IFUNIQUE<br />**-MAGECINC member/modifier<br />The -IFUNIQUE command must immediately precede the -MAGECINC, as shown above. It applies to the member named in the (cont.)<br />-MAGECINC which immediately follows it.. You can use as many of the -IFUNIQUE and as many -MAGECINC commands in one (cont.)<br />Rule, or in one program, as you need.<br />The -IFUNIQUE works even if another -MAGECINC for the same member appears physically behind this one in the program. (cont.)<br />The -IFUNIQUE feature is not limited only to Business Rules, it can be used anywhere, but it is particularly useful in (cont.)<br />Business Rules.<br />## <br />Restrictions in Rules<br />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.<br />Never code references to screen fields**, except for the four standard fields which MAGEC forces all screens to include. They are:<br />SFUNCT function code - 6 characters<br />**SKEY free-form key - 31 characters<br />SCOMPL completion message - 40 characters<br />SERRMSG error message area - 240 characters<br />This includes all the associated attribute, color, highlighiting, position, and error flag fields for them.<br />You can, however, refer to screen fields indirectly using MAGEC's symbolic screen field references**.<br />Never code **references to datanames** except those that are either:<br />1) defined in the RULWORK code for this Rule.<br />**2) defined as standard fields in all MMP's.<br />3) defined in the Element copybook for the Element this Rule is associated with.<br />4) Cobol special registers available to all programs.<br />Never code references to paragraph names** except those that are either:<br />1) defined in this RULPROC logic.<br />**2) generated into all MMP's by MAGEC.<br />Never GO TO** paragraph names except those that are both:<br />1) within the BB600 through BB699 routine.<br />**2) defined in either every MMP, or within this RULPROC logic.<br />To exit **the RULPROC logic you should GO TO BB699-EXIT.<br />## <br />Setting Default Values<br />SInce the RULPROC coding is inserted into the MMP as the last process before the data is actually updated to the (cont.)<br />database, you will find that this is a handy facility for testing for "null" values in fields and setting default (cont.)<br />values for them. This gives the DBA control over default values and relieves the application programmers from that (cont.)<br />chore. The result is more consistent handling of data across many applications.<br />## <br />Preventing Updates<br />The most obvious purpose for Business Rules is to prevent data from being placed onto the database unless it passes (cont.)<br />stringent validation requirements. These validations can involve cross-field, or even, cross-file, comparisons. The (cont.)<br />RULPROC logic is inserted just before the actual database update in the generated MMP's; therefore it can set an error (cont.)<br />flag to cause the MMP to bypass the update and issue an error message instead. You do that by (cont.)<br />coding:<br />MOVE 'xxx' TO ERROR-NUMBER<br />**PERFORM CA100-LOAD-ERR-CODE-TBL THRU CA199-EXIT.<br />where:<br />xxx<br />= the (alphanumeric) number of the error message you wish to have issued.<br />That is exactly how it is done in the customization editing that a programmer does for an MMP, except that s/he would (cont.)<br />usually also set the screen field's error flag for the screen field being edited. In the Business Rules, you are (cont.)<br />editing database fields, not screen fields. All of the screen data has been moved to the database before your RULPROC (cont.)<br />logic was invoked. You can; however, set the attributes for the four standard MAGEC screen fields, and you can make use (cont.)<br />of MAGEC's symbolic screen field referencing discussed later in this section.<br />## <br />Creating "Master" Record<br />In some instances you might wish to automatically generate a "master record" when a "detail record" is added, if no (cont.)<br />master record already exists. A possible example: generate an invoice header when the first invoice line item is added, (cont.)<br />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.)<br />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.)<br />the screen (SFUNCT) to the one which will display that new master record; the default logic ot the MMP's will then (cont.)<br />display the screen with the "data ADDED to database" message in SCOMPL, and the new function code in SFUNCT, ready for (cont.)<br />the operator to press ENTER to display the master record's data<br />or to update it.<br />## <br />Assigning Keys<br />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.)<br />obtain the next available key value. This relieves the application users from having to determine a new key and gives (cont.)<br />you, the DBA, control of new keys added. The new key values might be check digit'ed numbers.<br />The Business Rules are a handy place to accomplish the setting of the new key into the new record. You can access a (cont.)<br />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.)<br />assigns key values.<br />If you had a Journal Entry file whose key was Voucher Number, you might have many different programs which could add (cont.)<br />new Journal Entries. Because of your Business Rule logic to assign Voucher Numbers (perhaps by calling a subroutine), (cont.)<br />none of the MMP's or their authors had to bother themselves with "how to assign a Voucher Number" and you are assured (cont.)<br />that all Voucher Numbers are assigned correctly (or, at least, uniformly).<br /># <br />Referential Integrity<br />## <br />Deletion Rules<br />Another feature, related to Business Rules, is called "Deletion Rules". This enables the DBA to specify logic to be (cont.)<br />triggered (invoked) whenever a record (containing the specified element) is to be deleted.<br />The restrictions which apply to the Procedure Division coding for a Business Rule (RULPROC) also apply to the coding of (cont.)<br />a Deletion Rule (RULDELT). Please refer to the previous topic in this chapter for full descriptions. The only (cont.)<br />difference is that the modifier RULDELT is used instead of RULPROC. Any work areas needed for the RULDELT logic are to (cont.)<br />be defined in the RULWORK coding, just as they are for RULPROC. Do not define the same work field twice since all three (cont.)<br />of these members (RULWORK, RULPROC, and RULDELT) will be inserted into each MMP which updates the specified (cont.)<br />element.<br />To add a Deletion Rule for the CUS01 element, you would use the command:<br />RULADD CUS01/RULDELT<br />The code that you provide for RULDELT will be inserted into the generated MMP's in the BB400-EDIT-FOR-DELETE paragraph. (cont.)<br />The exit from that routine is BB499-EXIT**. In all other respects the RULDELT coding must follow exactly the same (cont.)<br /><br />next: db06.md.txt