03 DB-RETURN-CODE PIC X(2).<br />88 NOT-FOUND VALUE '14'.<br />88 REC-FOUND VALUE ' '.<br />88 DUP-RECORD VALUE '10'.<br />03 FILLER PIC X(61).<br />03 DB-KEY-VALUE PIC X(256).<br />03 AUDIT-STAMP-AREA.<br />-MAGECINC ELT00-C<br />01 FILLER.<br />03 DB-ELT00 PIC X(6) VALUE SPACE.<br />03 DB-ELT-LIST.<br />05 DB-ELT OCCURS 17 TIMES PIC X(6).<br />01 DB-DATA-AREA.<br />..... insert -MAGECINC's for element copybooks here .....<br />```** <br />The exhibit shows the standard areas. The ELT00-C copybook expands to define the 36-byte audit stamp.<br />## <br />File Opens<br />When using the batch I/O module you have several options as to the opening of files you will be accessing. Special database commands are provided to give you the flexibility needed for your programs.<br />MAGDBMS will automatically open a file the first time you access it, if it is not already opened. This is known as an (cont.)<br />implicit open. This enables you to easily convert programs which were originally written to access Datacom/DB (which (cont.)<br />also normally uses the implicit open).<br />There are two ways that a file can be opened: open for update and open for read only. Unless you alter the default (cont.)<br />parameter, an implicit open will be for read only. If you wanted to alter the default so that implicit opens were for (cont.)<br />update, you would use the *LOAD command. To alter the default back to read only, use the *READ (cont.)<br />command.<br />You can also do an explicit open of a file by using one of two commands: OPENU or OPENR. The OPENU command opens the file for update, the OPENR command opens the file read only.<br />You can explicitly close a single file or *all *open files. The CLSFL command will close a single file, you specify it (cont.)<br />by the Element names in the element list. The *CLSE command closes all open files.<br />## <br />Batch Security<br />The same rules regarding the audit stamp apply in batch as in online programs. You may interrogate, but not update, the (cont.)<br />audit stamp. MAGDBMS automatically posts to it when you add or update. Pseudodeletion is also supported from the batch (cont.)<br />I/O module.<br /># <br />Where-Used Reporting<br />## <br />MAGECLBR<br />In the course of developing and maintaining applications we often find the need to know where a certain Data Item (cont.)<br />(field) or a certain Element is being used throughout all systems. This enables us to determine the impact of some (cont.)<br />proposed change before actually making it. It can also help us to ensure that various items of data are treated (cont.)<br />uniformly across systems. The MAGECLBR utility program produces a formatted Where-Used report for either an Element or (cont.)<br />an "include member". The online global search facility incorporated into the LBRSEE function allows a search for all (cont.)<br />references to a specific Data Item.<br />To use MAGECLBR to produce a Where-Used report, execute the jobstream MAGLBREX (described in the "Offline Utilities" chapter) with one of the following control cards:<br />-MAGECUSE ELT eeeee<br />where:<br />eeeee<br />= Element name<br />-MAGECUSE LIB nnnnnnnn/mmmmmmmm<br />where:<br />nnnnnnnn<br />= member name<br />mmmmmmmm<br />= its modifier (as appropriate)<br />-MAGECUSE DIT xxxxxxxxxx<br />where:<br />xxxxxxxxxx<br />= dataname (may be generic using dot or asterisk)<br />-MAGECUSE TBL ttt<br />where:<br />ttt<br />= table number<br />-MAGECUSE DOM domainname<br />where:<br />domainname<br />= domain name (up-to 20 characters)<br />MAGECLBR will search for all references in both online MMP's and in batch MBP's, or in any other programs which have (cont.)<br />their source code catalogued to the MAGEC library. You can catalogue "raw" source code to the library using MAGECLBR (cont.)<br />with a control card as follows:<br />-MAGECADD LIB nnnnnnnn/mmmmmmmm<br />followed by the data to be catalogued. Further information about MAGECLBR can be found in the "Offline Utilities" and "Librarian" chapters.<br />To do a global search online for references to a dataname (or other character sequence) enter:<br />LBRLST 1<br />(a list of members will appear)<br />Next, position the cursor down to the first item on the list (or whichever member you would like to begin your search (cont.)<br />with) and press the ENTER key. Next, key the desired dataname (or character string) into the **Search Arg** field and (cont.)<br />key<br />$GBL<br />into the **Password **field and press the ENTER key. You will be presented every reference to the desired dataname and (cont.)<br />instructed to press ENTER to continue searching after each one. The member names and their modifiers (if appropriate) (cont.)<br />will be shown on the top lines of the display. This same facility can be done using the ALGLST 1 command to begin the (cont.)<br />search, instead of the LBRLST 1 command. In that case you would be scanning Customization Algorithms rather than (cont.)<br />ordinary Library members.<br />## <br />SCDTBL<br />There is an online function which you can use to search for references to a MAGEC table. It will display a list of (cont.)<br />applications which have a given table number specifed as the lookup table for a screen field. The command (cont.)<br />is:<br />SCDTBL nnn<br />where:<br />nnn<br />= the desired table number (001 through 255)<br />In order to limit online overhead the search is subjected to the standard "scan limit" or 1000 I/O's before it is interrupted. You can press ENTER to continue the search; however, if you wish.<br />## <br />DCLDOC<br />A special batch utility program is provided (MAGEC version 2.1 and later) to produce complete documentation for a Data (cont.)<br />Class, including where-used reporting. The DCLDOC program accepts a control card (multiple control cards are permitted) (cont.)<br />specifying the 3-character name of the Data Class for which you wish documentation printed. It reports on all Keys, (cont.)<br />Elements, Data Items, Business Rules, and references. The where-used reference report shows both primary and joined (cont.)<br />references for both online MMP's and batch MBP's.<br />To invoke the report, execute DCLDOC with a control card as:<br />DCLDOC xxx<br />where:<br />xxx<br />=a Data Class name in columns 8-10 of the control card<br />If you wish to have all lowercase alphabetics in the printed oputput converted to uppercase, use a control card as:<br />DCLDOC xxx U<br />where:<br />U<br />= literal "U" in column 12, a "Y" is equivalent to "U".<br />## <br />Business Rules<br />When you are entering or maintaining Business Rules online it is often useful to be able to see a where-used report to (cont.)<br />indicate which programs will be affected (need to be recompiled) if you alter this rule. From any of the RULxxx or (cont.)<br />ELTxxx functions' screens you can press PF6 to request such a report. The results wil be displayed to you online. You (cont.)<br />could also enter the command:<br />RULUSE eeeee<br />where:<br />eeeee<br />= the desired element name<br />## <br />Domains<br />Global Changes<br />An offline facility is provided to help you to make global changes based upon Domain definitions. This enables you, for (cont.)<br />example, to change all zip codes from five digits to nine digits. That assumes, of course, that all zip code fields in (cont.)<br />all files are defined as belonging to the same Domain.<br />To make such a global change you would first alter the definition of the Domain. This is done online using the DOMCHG (cont.)<br />function. Next you should run a where-used report to give yourself documentation of all references that are going to be (cont.)<br />altered. *You may skip this step at your own peril!* The global change operation will also produce a report of what was (cont.)<br />changed, but you might prefer to know what will be changed beforehand, then compare it to the report produced (cont.)<br />after-the-fact.<br />Finally you would execute the global change operation. To do so you would execute the MAGECLBR batch utility using a control card of:<br />-MAGECGBL DOM dddddddddddddddddddd<br />where:<br />dddddddddddddddddddd<br />= the desired Domain name<br />This operation will alter the Data Item definitions for all fields affected. It will not alter any Element, Data Class, (cont.)<br />Key, or file definition (i.e. IDCAMS) parameters. It is up to you to make any needed changes to record lengths, key (cont.)<br />lengths, element lengths, or displacements. It may also be necessary to unload, reformat, and reload the data from the (cont.)<br />files. The reports produced should provide you with a checklist of modified Data Items and Elements<br />the rest is up to you.<br /># <br />File Reorganization<br />MAGEC's dictionary files are simple VSAM KSDS (on the mainframe) or standard indexed files (on the PC). They are single (cont.)<br />key files (no alternate indices). They should be occasionally backed up and reorganized to maintain optimum (cont.)<br />performance. The method used to reorganize these files is no different from the method used to reorganize other such (cont.)<br />files in your environment. MAGEC provides some assistance in the form of pre-coded IDCAMS (or AMSERV) control cards (on (cont.)<br />the mainframe) and a .BAT file (on the PC).<br />## <br />Mainframe<br />There are three members on the MAGEC library (ALG file) which will help you to reorganize the dictionary VSAM files. They are:<br />IDCAMBKP/REPRO<br />**IDCAMRST/REPRO<br />DEFFILES/VSAM<br />The procedure for reorganizing and backing up the files involves:<br />1)<br />backup to tape using the IDCAMBKP/REPRO control cards,<br />2)<br />deleting and redefining the files to the VSAM catalogue using the DEFFILES/VSAM control cards, and<br />3)<br />reloading the files using the IDCAMRST/REPRO control cards with the tape from step 1 as input.<br />The control cards provided are merely samples. You may wish to customize them for your particular environment. In the (cont.)<br />backup and restore control cards you will notice the NOREWIND parameter specified. The MVS version of IDCAMS does not (cont.)<br />support that option, so you will want to remove it if you are an MVS installation.<br />## <br />PC<br />The PC (simulated) VSAM files can be reorganized using a .BAT or .CMD file provided with MAGEC. It is necessary to have (cont.)<br />enough disk space available on your hard disk drive to hold another copy of the file being reorganized since the (cont.)<br />process involves copying the file to a new, reorganized file and then erasing the old one and renaming the new one to (cont.)<br />the proper name. All simulated VSAM files in MAGEC have an extension of .DAT (for your information). The .BAT file is (cont.)<br />named: REORG.BAT and is in the \MAGMF\JCL directory. To invoke it, at the DOS prompt enter the (cont.)<br />command:<br />REORG xxx<br />where:<br />xxx<br />= the Data Class name to be reorganized)<br />Although this procedure is generally very safe, it is smart to first backup your hard disk to tape (or other medium) before doing any reorganizations.<br />## <br />TWA File Purge<br />The TWA file is used by all online transactions as a place to store data to be passed from transaction to transaction (cont.)<br />and from program to program. There are several different types of records stored on the file for various purposes. Some (cont.)<br />of them are simply to provide pseudo-conversational processing for all transactions without imposing the need for the (cont.)<br />programmer to handle the saving of passed data and so forth. Other types of records are used by the online help (cont.)<br />facility, window swapping, and other integral features of MAGEC.<br />The records on the TWA file have various different keys that identify what they are for; however, in all cases the keys (cont.)<br />are eight characters long and begin with the four-character terminal ID that makes the keys unique. This scheme also (cont.)<br />gathers all records for a given terminal in physical proximity to one another.<br />*Regular reorganizations of the TWA file are highly recommended.*<br />All of the records on the TWA file are dynamically created (added) whenever they are first needed, then they are reused (cont.)<br />(updated) as they are subsequently needed. For example, online documentation records will be created the first time (cont.)<br />that online documentation is used at a given terminal, then merely updated as online documentation is subsequently used (cont.)<br />at that terminal.<br />This scheme works well and reduces overhead significantly; however, it has one drawback. The TWA file can become (cont.)<br />over-populated with records for terminals that are no longer active. There are three good methods for solving this (cont.)<br />problem.<br />*First*. You can totally purge the TWA file and re-initialize it. This lets MAGEC dynamically re-add any needed records (cont.)<br />as the need for them arises. The adding of records is less efficient than updating in place, but the penalty is usually (cont.)<br />small and this method is a sure-fire way to solve the over-population problem.<br />To do this you should execute the IDCAMS DELETE/DEFINE, then execute MAGINIT to initialize the file. This could even be done in the online startup JCL, if desired.<br /><br />next: db08.md.txt