Proper use of the Domain facility of MAGEC will enable MAGEC to further automate the application development processes, specifically the logical joining of files.<br />Consider the situation in which you have two Data Classes (files), as:<br />CUS Customer data<br />**IVC Invoice data<br />Now, suppose that the key to the customer data was customer number, which was defined as a Data Item named (cont.)<br />"CUS01-CUSTNO". Also suppose that there is a Data Item in the invoice record named "IVC01-CUST", and that it contains (cont.)<br />the customer number. Further suppose that both these Data Items are defined as belonging to the Domain (cont.)<br />"CUSTOMER-NUMBER". MAGEC now has enough information to know that it can construct an exact key for the customer file by (cont.)<br />MOVE'ing IVC01-CUST to CUS01-CUSTNO; therefore, it can fully automate the logical join process when an application (cont.)<br />needs to access the invoice data and join customer data.<br />Logical joining can be done without any Domain definitions or usage; however, it involves more effort by the (cont.)<br />application developer to build the key used to access a file. Use of the fully automated joining via Domains also gives (cont.)<br />the Database Administrator better control over how data is accessed.<br />Figure 27 -- Join Via Domains<br />## <br />Suggestions Regarding Domains<br />The process used to automatically join data can be repeated for many levels. Thus, after reading the Invoice data and (cont.)<br />then joining the Customer data to it, you could possibly use the ZIP code from the Customer data to join another file (cont.)<br />which is keyed by ZIP code, and so on. You can even concatenate data items from more than one file to build the key to (cont.)<br />access another file. This automatic logical join facility is potentially powerful enough to eliminate almost all manual (cont.)<br />coding of file accesses by programmers. It depends, however, on your properly defining and using Domain (cont.)<br />definitions.<br />We suggest that you should always try to identify and specify Domain Names for those Data Items which are part of (or (cont.)<br />all of) a record key. Likewise you should always try to specify (the same) Domain Names for foreign keys within your (cont.)<br />records. This will not only help automate application development, it will also give you excellent documentation of (cont.)<br />relationships between Data Classes. The Where-Used reports and screens will be much more valuable to you than if you (cont.)<br />haphazardly (or not at all) use Domains.<br />When designing new files/tables, you should give consideration to identifying Domains for as many of the new Data Items (cont.)<br />as possible. This will help you to ensure uniform definitions and usage. You should also try to apply those Domain (cont.)<br />definitions to your existing Data Items--the minimum you will gain is a knowledge of which ones are inconsistent, the (cont.)<br />maximum is global standardization.<br />The offline utility program, MAGECLBR, contains a function to report usage for any Domain Name. It also has a function (cont.)<br />to make any necessary alterations to all Data Items belonging to a Domain in order to make them compatible. This would (cont.)<br />enable you to, say, change ZIP-CODE from a 5-digit numeric to a 9-digit numeric GLOBALLY*. Obviously, Element and (cont.)<br />record lengths might need to be adjusted after you did this. The control cards for MAGECLBR to produce a Where-Used (cont.)<br />report and to globally alter definitions are, respectively:<br />-MAGECUSE DOM dddddddddddddddddddd<br />-MAGECGBL DOM dddddddddddddddddddd<br />&nbsp;<br />Where ddddddddddddddddddddd is the Domain Name. The Where-Used report will note any inconsistencies without altering (cont.)<br />any definitions. You should use it whenever you have a question regarding any given Domain.<br />You can get a quick online Where-Used display for any Domain by simply displaying its definition (using DOMSEE), and (cont.)<br />pressing PF6. The information will not be as thorough as from the hardcopy report from MAGECLBR, but it is often (cont.)<br />sufficient and it is much handier to obtain.<br />When adding Domain definitions, remember that they are identified by a six-digit unique number, and that the numbers (cont.)<br />from 000001 through 000100 are reserved for "figurative constant" or "literal" Domains, which have special meaning for (cont.)<br />the automatic logical join process.<br />*MAGEC Software* has plans to implement additional features which are to be driven by these Domain definitions in future releases of MAGEC. Your input and ideas will be appreciated.<br /># <br />Appendix A -- Deleting Definitions<br />## <br />Restoring/Reloading MAGEC Dictionary<br />For a number of reasons this project, and the other turorial projects, are best done on a microcomputer, rather than on (cont.)<br />a mainframe. Being the sole user of the system allows you to do things which would be very un-neighborly on a (cont.)<br />multi-user mainframe. If you are doing this project on a PC or PS/2 using the PC version of MAGEC, you might be able to (cont.)<br />simply re-install part of MAGEC's dictionary to delete the VAD definitions. Using the initial installation diskettes (cont.)<br />you could, at the DOS prompt, enter the commands:<br />C:<br />CD\MAGEC<br />RESTORE A: DCLK1.DAT<br />RESTORE A: KYFK1.DAT<br />RESTORE A: ELTK1.DAT<br />RESTORE A: ALGK1.DAT<br />This assumes that your \MAGEC directory is on the C: drive and that the diskettes are on the A: drive; you may need to adjust the above for your particular situation.<br />## <br />Un-Defining VAD Data Class<br />Whether you are using a PC or mainframe you can un-define the VAD Data Class. To delete all definitions for the sample VAD Data Class and all subordinate entities:<br />In all environments:**<br />Online, in MAGEC, do the following functions:<br />DITPUR VAD01<br />LBRPUR VAD01-C<br />RULPUR VAD01<br />ELTDEL VAD00<br />ELTDEL VAD01<br />KYFDEL VADK1<br />DCLDEL VAD<br />**On a PC:**<br />*Also*, issue the following command from the DOS prompt:<br />ERASE C:\MAGEC\VADK1.DAT<br /># <br />Appendix B -- DB Commands<br />The following is a list of DB Commands which may be used with DBDITO. For more detailed information, please refer to (cont.)<br />the *MAGECIO Commands* topic in the "Database Administration" chapter (section, Accessing Files from (cont.)<br />Programs).<br />COMMAND FUNCTION <br />REDKY read record for key value in the screen data area<br />REDNX read the next record from the one just read<br />REDPR read the previous record (not on Datacom DB)<br />REDID re-read the record just read<br />RDUKY same as REDKY but with intent to update<br />RDUID same as REDID but with intent to update<br />RDUNX same as REDNX but with intent to update<br />LOCKY locate record with key = or > the screen data area<br />LOCKX locate record with key = the screen data area<br />LOCNX locate next record from one just read or located<br />FSTAT test file status (open or closed, etc.)<br />REDLE read the record just located<br />UPDAT update the record<br />DELET delete the record<br />RELES release the record just read-with-intent<br />ADDIT add a record<br />**<br />NOTE:<br />**<br />Datacom/DB supports all of the above commands plus a list of additional ones. If you are accessing a Datacom/DB (cont.)<br />file/database, you can use any legal command and it will be passed through to Datacom's DBENTRY entry point and the (cont.)<br />results displayed to you.<br /># <br />Appendix C --&nbsp; Edit Type Codes<br />## <br />Automatic Editing<br />When you define your mask using MSKDEF, or when you modify it after having allowed the auto-paint feature to generate (cont.)<br />it for you, you can specify to MAGEC that you desire automatic editing to be done to screen fields. You do this by (cont.)<br />specifying, for each field, an edit type code.<br />These same edit type codes are also specified in the dictionary definitions for data items (DIT's). When you use the (cont.)<br />auto-paint feature (for online screens) or the automatic report program generation (as in the "Batch Developer" (cont.)<br />Tutorial) MAGEC sets the screen or report editing formats based upon the edit type codes found in the DIT definitions. (cont.)<br />You can override them in the MSKDEF or RPTDEF functions if you need to.<br />There are three general categories of edit types:<br />AlphaNumeric<br />Numeric<br />Dates<br />The Cobol copy book for a mask or the detail line definition for a report will contain appropriate Cobol edit patterns (cont.)<br />(ie.&nbsp;ZZZ.99-) based on the edit type. You might refer to the chapter, "Analysis of the Generated MMP" (found in (cont.)<br />the *Programmer's Reference Guide*) for more detail.<br />For numeric fields there is also a specification as to how many digits left of the decimal point and right of the decimal point are allowed.<br />One of the alphanumeric types is "T", that means table lookup validation. Operator entries will be validated by looking (cont.)<br />them up in a MAGEC lookup table. You can define lookup tables and the valid entries in those tables. Refer to the MAGEC (cont.)<br />"Database Administration" chapter for further details about lookup tables.<br />## <br />Table of Edit Types<br />AlphaNumeric Edit Types:<br />X<br />Miscellaneous fields, any characters will be accepted. Example: company name, comments.<br />b<br />Same as X.<br />A<br />Alphabetic (A-Z and blank) characters only. Example: person's name, city name.<br />U<br />Uppercase. Any characters will be accepted as valid, lowercase alphabetics will be converted to uppercase by MAGEC.<br />T<br />Table lookup. Same as U plus MAGEC will validate entry against a lookup table.<br />W<br />Where to display a description from a lookup table. Used in conjunction with a T field. MAGEC moves the description from the found entry in the table to a W field.<br />P<br />Pattern edited alphanumeric field.<br />Numeric Edit Types:<br />N<br />Numeric, MAGEC will pad with leading zeros.<br />S<br />Numeric, MAGEC will suppress leading zeros.<br />=<br />Same as S, plus trailing minus sign.<br />Z<br />Same as S, plus comma insertion.<br />-&nbsp;<br />(hyphen)<br />Same as Z, plus trailing minus sign.<br />$<br />Same as Z, plus floating dollar sign.<br />#<br />Pattern edited numeric field.<br />Date Edit Types:<br />M<br />MM/DD/YY or MM/DD/CCYY (2 or 4-digit years).<br />D<br />DD/MM/YY or DD/MM/CCYY (2 or 4-digit year).<br />Y<br />YY/MM/DD or CCYY/MM/DD (2 or 4-digit year).<br />**<br />NOTE:<br />**<br />When the operator enters data into screen fields MAGEC accepts any valid, unambiguous format depending upon the edit type. For instance, in a type-$ field the operator may enter:<br />12345.5 or,<br />**1,234.50 or,<br />$1,234.50 etc.<br /># <br />Appendix D --&nbsp; User Abend<br />Sometimes you might wish to abend an online task issuing an error message to the operator. This is useful when you wish (cont.)<br />to cause Transaction Backout to be invoked, or when you just want to stop processing because your program has sensed (cont.)<br />error conditions beyond its capacity to deal with.<br />This can be accomplished easily via the ABEND command which is handled in MAGEC's I/O module.<br />To use the ABEND command, code:<br />MOVE 'ABEND' TO TWA-DB-REQUEST.<br />&nbsp;<br />MOVE xx TO TWA-DB-RETURN-CODE.<br />&nbsp;<br />MOVE 'mmmmm' TO SCOMPL.<br />&nbsp;<br />PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT.<br />&nbsp;<br />In the above example, xx is a two-character abend code which you may set. MAGEC will abend the task issuing a CICS (cont.)<br />abend code of MUxx (MU is for MAGEC USER ABEND). The mmmmm is any 40-character message you would like (cont.)<br />displayed.<br />NOTE:<br />**<br />Control passes to the I/O module which aborts the task. Control does not return to your program. If an Abend Handler (cont.)<br />program has been specified for either your MMP (refer to the definition of the "Screen Header" in the Application (cont.)<br />Developer Tutorial) or for the User View (refer to the discussion of "Global Parameters" in the *Installation Guide*), (cont.)<br />then the Abend Handler program will be invoked. Since you can code an Abend Handler program, it might do anything you (cont.)<br /><br />next: data10.md.txt