Referential Integrity ## Deletion Rules Another feature, related to Business Rules, is called "Deletion Rules". This enables the DBA to specify logic to be (cont.) triggered (invoked) whenever a record (containing the specified element) is to be deleted. The restrictions which apply to the Procedure Division coding for a Business Rule (RULPROC) also apply to the coding of (cont.) a Deletion Rule (RULDELT). Please refer to the previous topic in this chapter for full descriptions. The only (cont.) difference is that the modifier RULDELT is used instead of RULPROC. Any work areas needed for the RULDELT logic are to (cont.) be defined in the RULWORK coding, just as they are for RULPROC. Do not define the same work field twice since all three (cont.) of these members (RULWORK, RULPROC, and RULDELT) will be inserted into each MMP which updates the specified (cont.) element. To add a Deletion Rule for the CUS01 element, you would use the command: RULADD CUS01/RULDELT The code that you provide for RULDELT will be inserted into the generated MMP's in the BB400-EDIT-FOR-DELETE paragraph. (cont.) The exit from that routine is BB499-EXIT**. In all other respects the RULDELT coding must follow exactly the same (cont.) restrictions as apply to RULPROC. You can do virtually any type of processing in the RULDELT logic, including I/O and complex field content or value (cont.) checking. Deletion Rules can serve several very important functions associated with ensuring referential (cont.) integrity. ## Prevent Deletion (Restrict) In the RULDELT code you could, perhaps, test for the existence of subordinate items (e.g. test for existence of (cont.) invoices on file for a customer you are about to delete) and, if found, set the ERROR-FOUND condition to prevent the (cont.) deletion from taking place. Another reason you might wish to prevent the deletion of an item is because of certain data item contents. For example, (cont.) if the customer's balance is not zero. You might even wish to prevent deletion of certain cirtical records based on (cont.) their ID, e.g.: customer numbers 00001 through 00100 may not be deleted, ever. You can test for PF keys in this logic. You might even wish to create a Deletion Rule which states that customer numbers 00001 thru 00100 *can *be deleted if you press PF14 (or some other key). ## Auto Delete (Cascade) Another possibility would be to automatically delete any invoices for the customer about to be deleted. ## Alter References (Nullify) Another scenario involves not deleting the invoices, but rather, modifying them so that they now reference a different (cont.) customer. One possibility is to have them reference a "dummy" customer number that is used for miscellaneous "walk-in" (cont.) business. ## Other Processes Many other types of processing are possible in the RULDELT logic. Some examples of them are: Control Record Update You could update a control record, perhaps the salesman's record to reflect one less customer. Master Deletion When deleting the last invoice for a customer you might wish to delete the customer's master record. Audit Trail Generation You might wish to generate a record on a log file whenever certain data is deleted. There is virtually no limit to the types of processing you might wish to apply in the Deletion Rules. Remember, it will (cont.) be invoked just prior to to standard MMP logic to delete a record. If you set the ERROR-FOUND condition (usually by (cont.) performing CA100-LOAD-ERR-CODE-TBL) then the delete will not be done. As an example: IF CUS01-BALANCE GREATER THAN ZERO ** 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. # Symbolic Screen Field References ## In Business Rules As discussed earlier, you should never directly reference screen fields from within a Business Rule or Referential (cont.) Integrity Rule. This is because your Rules will likely be inserted into several programs (MMP's) and you have no way of (cont.) knowing what name the screen field associated with a given database field might have, or even that there is a screen (cont.) field associated with that database field. This restriction presents an inconvenience in that it would be helpful, and more consistent with the way MAGEC screens (cont.) tend to behave, if you could access the screen fields -- especially the error flags and attribute bytes. This would (cont.) enable you to use MAGEC's standard error handling features which highlight error fields and home the cursor to them, or (cont.) to display values in screen fields, or to manipulate attributes and position the cursor. Fortunately, there is a way you can do all these things from your Rules. Though you must not refer to any screen fields (cont.) (except for the four standard fields, as noted earlier) directly by their Screen Field dataname, you can refer to them (cont.) indirectly using symbolics based upon the database field's dataname. Such symbolic references are coded using the (cont.) database name enclosed in at-signs (@). For example: MOVE ATUADHNF TO @CUS01-AMOUNT-DUE@A. MOVE @CUS01-AMOUNT-DUE@-POSN TO TWA-MSK-CUR-AD-OT. would set the attribute for the screen field associated with the database field "CUS01-AMOUNT-DUE" to high-intensity, (cont.) unprotected; and it would position the cursor to that screen field. In the application developer's generated MMP, this (cont.) code would be translated into: MOVE ATUADHNF TO SFIELDA. MOVE SFIELD-POSN TO TWA-MSK-CUR-AD-OT. assuming, of course, that the name of the screen field associated with CUS01-AMOUNT-DUE was 'SFIELD'. That screen field (cont.) dataname might well be different in several programs which each reference this database field; the translation would, (cont.) automatically, be adjusted accordingly. This allows you to refer to screen fields without having to know their (cont.) names. If the database field in question happens to be an arrayed field (it has an OCCURS clause), then you must include the occurrence number (maximum of 3 digits) within the at-sign brackets, e.g.: MOVE ATSADHNF TO @CUS01-ADDR (2)@A. Notice that the expression within the at-sign brackets is converted into the screen field's dataname, without any of (cont.) the suffixes appended. You can code the desired suffix immediately behind the closing at-sign (no space between them) (cont.) to reference any of the datanames in the screen definition. You could refer to the "Screen Painting" and "Color 3270" (cont.) chapters of the *Programmer's Reference Guidel* for detailed discussions of the datanames in the screen mask copybook. (cont.) Here is a quick review: Assuming that the screen field has a dataname of "SFIELD", the possible datanames found in the copybook would be: SFIELD the screen field itself, implied or explicitly PIC X(nn). SFIELDA the attribute byte SFIELDE the error byte for this field SFIELD-ED the Cobol edit picture, redefining SFIELD (if a numeric field) SFIELD-POSN the screen position of the start of this field SFIELD-COLOR the 7-color code (if a 7-color field) SFIELDH the extended highlight code (if a 7-color field) SFIELD-JULIAN-DATE the julian equivalent (if a date field) SFIELD-DAY-OF-WEEK the day of week code (if a date field) SFIELD-N the numeric value (if a numeric field) SFIELD-YY the year (if a date field) SFIELD-MM the month (if a date field) SFIELD-DD the day (if a date field) SFIELD-CC the century (if a date field with 4-digit year) You can reference any of these datanames in the mask copybook using symbolic references plus the appropriate suffixes. For example, to set the error flag for a field: MOVE E TO @XXX99-FIELDNAM@E ## Conditional References The symbolic references allow you to access screen fields without knowing their names. That solves half of the problem (cont.) we described. The other half of the problem arises when we try to reference a screen field associated with the database (cont.) field but some applications do not even display this data on the screen. In other words, there* is no* screen field. Once (cont.) again, you have no way of knowing or controlling this at the time you define your Rules. The solution to this problem would be to make your references "conditional"; to state "if a screen field exists, then (cont.) do so-and-so". You can do exactly that using MAGEC's conditional reference feature. To use this feature you must (cont.) precede *each* symbolic reference with the -IFEXIST control statement. For example: -IFEXIST MOVE ATUADHNF TO @CUS01-AMT@A. ins in column 1, the Cobol line begins in column 11 (or beyond), just like any other Cobol statement. If there is no screen field associated with CUS01-AMT (in this example), the entire Cobol line will be ignored made into a comment line via an asterisk in column 7. If the line ends with a period (.), however, MAGEC will generate (cont.) a "dummy" statement with a period at the end of it in order to avoid possible logic problems caused by a missing (cont.) period. As a result, the above coding might be translated differently in two different MMP's. In an MMP having a screen (cont.) field associated with CUS01-AMT you might see: MOVE ATUADHNF TO SAMTA. In an MMP not having a screen field associated with CUS01-AMT, you might see: * MOVE ATUADHNF TO @CUS01-AMT@A MOVE SPACE TO SPACE-CHAR. Now you have the ability to manipulate screen fields from within your Rules, so long as you use symbolic references and render them conditional. If you code two symbolic references on one line of code, and you have preceded the line with an -IFEXIST; if either (cont.) reference fails the -IFEXIST test then the entire line will become a comment as shown above. In MAGEC's screen painter there is nothing to prevent you from defining multiple screen fields with the same database (cont.) field specified as the source/target for all of them. This may even be a useful technique in some cases. If you code a (cont.) symbolic reference using a database field name that is associated with more than one screen field, you will receive a (cont.) warning message (in the generated code) telling you that this is an ambiguous reference; MAGEC will generate the (cont.) translation using the *first *match found. NOTE: ** We strongly recommend that you make every symbolic reference conditional within your Rules. To do so you must place an -IFEXIST statement before *each and every* symbolic reference. The symbolic screen field referencing and -IFEXIST features are available to Application Developers as well as to (cont.) Database Administrators. They are not limited to use only within Rules, but can be used anywhere in the Cobol (cont.) customization for online programs. The spelling for -IFEXIST may be either -IFEXIST or -IFEXISTS, they are equivalent. An example of the coding of multiple conditional symbolic references: IF CUS01-CITY EQUAL SPACES -IFEXIST MOVE @CUS01-STATE@A TO @CUS01-CITY@A -IFEXIST MOVE ALL '?' TO @CUS01-CITY@ -IFEXISTS MOVE E TO @CUS01-CITY@E  MOVE '123' TO ERROR-NUMBER - et cetera - # Version Verification ## The VERZUN Function The database administrator is often called upon to assist application developers to find and correct errors in their (cont.) applications. Our experience with MAGEC users over the years has taught us that a very large percentage of the problems (cont.) developers encounter with their (MAGEC, or non-MAGEC) applications are caused by executing an old version of their (cont.) programs, or accessing an old version of a screen Mask, or executing a program compiled with an obsolete version of a (cont.) copybook. One of the values of a central, active dictionary is the ability to quickly ascertain which version is the (cont.) current one and which version is being executed. You could, of course, use the online inquiry functions of MAGEC to lookup the current version number (or date) for each (cont.) entity involved. That would take a few minutes and would depend upon your accurate navigation through the dictionary. (cont.) In addition you would need to view the actual load module of the program in question to determine (from the "core (cont.) mark") when it was generated and compiled. MAGEC provides a special online facility (for MAGEC online applications only) to enable you to obtain all the necessary information with a single inquiry. It is the VERZUN function. To use it online, enter one of the following commands: VERZUN MSKxxx VERZUN MMPyyy VERZUN yyy where: xxx = Mask number yyy = MMP number All of the above commands result in the same display. You have the option of giving either the MMP number or the MSK (cont.) number (usually they are the same, but not necessarily) as a key, either way you will be shown statistics for all (cont.) entities. You will be presented a display showing version dates and times for the program, screen, data definitions, (cont.) copybooks, etc. The display will also flag possible problems based upon its comparisons of these version (cont.) data. We feel that this should be one of the first steps a developer or DBA takes in trying to find a problem. A surprisingly (cont.) large number of "support calls" received at the MAGEC support center involve just such errors as are detected by the (cont.) VERZUN function. It might be a useful standard to always do the VERZUN function before calling for help since the (cont.) support technician will likely ask you to do it. In order for the VERZUN function to ascertain all of the needed data about an application, that application must have (cont.) been generated using version 2.0 (or later) of MAGEC. If the application was generated using an earlier version, you (cont.) will receive a message saying so. # Batch I/O Module ## MAGDBMS MAGEC provides a batch I/O module which accomplishes the same functions as the online I/O module. The entry point which your program calls is MAGECIO, the module is named MAGDBMS. When you generate a batch program (an MBP) and use the MBPCREAT jobstream to compile and link it, the MAGDBMS module (cont.) will automatically be included. This is true in both the mainframe and PC environments. In the mainframe environment (cont.) Next: https://magec.com/DOC/markdown/db05.md.txt