command to TWA-DB-CMD is identical to moving to DB-CMD, and so forth. The AA840-CALL-MAGEC-IO paragraph is also (cont.) included in the MBP's, as is the pointer field TWA-DB-AREA-A. Your MBP must be linked to include the MAGDBMS module. The sample jobstreams provided with MAGEC contain the (cont.) appropriate link coding for your environment (MVS, VSE, MS-DOS, VM, etc.). The jobstream is named MBPCREAT, it is a JCL (cont.) member for the mainframe and a .BAT or .CMD file for the PC. ## Logical Sequences of Commands The following sequence of commands will illustrate how you can control opening and closing files in a batch program. Assume a program accessing the ABC, DEF, and XYZ data classes. **Command** **MAGECIO action taken** beginning of program initial default open switch set to "read-only" LOCKY XYZ open XYZ read-only REDLE XYZ read located (first) record from XYZ *CLSE close all open files *READ set default open switch to "read-only" **(safe and harmless, but unnecessary here because that is the default and is still set from the job initiation) REDKY ABC open ABC read-only, read record by key OPENU DEF open DEF for update RDUKY DEF read DEF record for update by key UPDAT DEF update DEF record CLSFL DEF close DEF REDKY DEF open DEF read-only, read record by key *LOAD set default open switch to "open-for-update" REDKY XYZ open XYZ for-update, read record by key end of job close all files automatically # Audit Stamps ## Element 00 An Audit Stamp is a 36-byte portion of a record that is used to record Who, Where, and When the record was last updated (cont.) or added. It is an optional feature of MAGEC which may be specified for some Data Classes and not for others as needs (cont.) dictate. If Audit Stamp support is specified for a Data Class then the Audit Stamp must be defined as a separate (cont.) Element with a name in the format: eee00 Where: eee = Data Class name, 00 = literal value of '00' Whenever a program reads any Element(s) of the Data Class (with Audit Stamp specified) MAGECIO also automatically reads (cont.) the Audit Stamp Element into the area named AUDIT-STAMP. There is no need for you to provide copybooks to define the (cont.) Audit Stamp nor is there a need for the programs to include the Audit Stamp Element name (eee00) in the Element list. (cont.) It is illegal for any program to update an Audit Stamp Element and MAGECIO will abort the task if such an update is (cont.) attempted, a Return Code of 97 (Abend Code DB97) will be set. There is a standard copybook included into the Audit (cont.) Stamp area from the MAGEC library, it is named ELT00-C and contains the definition of any Data Class's Audit Stamp. The (cont.) definition includes: AS-FILE-NAME The Data Class name this record belongs to (3 characters long) AS-DATE-UPDATED The date (YYMMDD) this record was last updated or added (or pseudodeleted) AS-TIME-UPDATED The time (HHMMSS) this record was last updated or added (or pseudodeleted) AS-TERM-LAST-UPDATED The Device (Terminal) ID from which this record was last updated, etc. (4-char.) AS-OPER-LAST-UPDATED The initials of the operator who last updated (etc.) this record (3 char) AS-PROGRAM-LAST-UPDATED The name of the program (MMP) which last updated (etc.) this record (8 char) AS-EMPNO The Employee number of the operator who last updated (etc.) this (4-byte binary, 9-digit) AS-FILLER An unused byte reserved for future use AS-INACTIVE-FLAG A 1-byte flag that is set to HIGH-VALUE (X'FF') to indicate "pseudodeleted" by MAGECIO instead of actually deleting the record (if Real Delete = N on DCL file definition for this Data Class) # File Utility ## DBDITO Function There is a general purpose utility online Function provided with MAGEC which allows you to do any database request via (cont.) your CRT. It permits you to see and alter any file or database available to MAGEC using an over/under (cont.) character/hexadecimal display. It may be used to add, change, or delete as well as just look at data on the (cont.) files. To use this utility just enter the Function Code: DBDITO (full function) -or- DBUTIL (read only) The MAGEC security system governs who may use each of the above Functions and some additional restrictions also apply (cont.) because of the dangerous possibilities. DBDITO and DBUTIL are fully documented via the online HELP facility, press PF1 (cont.) after the screen is returned to you for full instructions. Some of the many common uses for the DBDITO utility are: Undeleting pseudodeleted records Correcting bad data on file Creating test data for new programs Verifying that a file is open/available Training the use of the MAGECIO Request & Commands You may refer to the MAGEC "Data Definition" tutorial for additional instructions on the use of DBDITO. # Logical Join ## Secondary Data Classes Very often the application developers will want to produce MMP's and MBP's which access more than one Data Class. For (cont.) instance, the MMP that is to provide inquiry and update capability for the Invoice data will also need to access the (cont.) Customer data to display name and address, etc. In a "flat file" or "relational" environment there are no physical "pointers" from one record to another; therefore the (cont.) connection between records is known as a "logical connection" and the process of specifying that connection is known as (cont.) "logically joining" the records. In the hypothetical Invoice MMP we mentioned above, the Invoice data would be the "Primary Data Class" and the Customer (cont.) data would be a "Secondary Data Class". There could be any number of additional Secondary Data Classes, but only one (cont.) Primary. In order to access the Secondary Data Class the developer must know: 1) which key (if there are more than one) (cont.) of that Data Class is to be used, and 2) how to construct the Key Value to be used. In our hypothetical example we (cont.) might wish to use the Customer-Number key of the Customer Data Class and, as the Key Value we might use the (cont.) Customer-Number from the Invoice record we are processing. A Data Item in the Primary data that is used as a key to access the Secondary data is known as a "Foreign Key". (cont.) Likewise, a Data Item from the Secondary data that is used to access yet another Secondary Data Class, is also known as (cont.) a Foreign Key. It is also possible to concatenate Data Items, from one or more Data Classes, in order to construct the (cont.) key to access another Data Class. It is also possible to access a Data Class by constructing only the high-order (cont.) portion(s) of the key and using a generic access, known as a "Partial Key Join". This would be appropriate if you were (cont.) using the Customer file as your Primary data and joining to the Invoice file, where ther may be many invoices for a (cont.) given customer. Specification of Logical Joining rules is done by developers as a part of the normal development process. In the (cont.) Semi-Automatic development sequence the developer will be prompted for all the necessary information and all the needed (cont.) coding will be generated for him. Alternatively he may manually do the coding using the Customization insertion points (cont.) named %JOIN and %DATADEF. In the Fully-Automatic development process MAGEC will generate the Logical Join coding with no help from the developer (cont.) other than to select which Data Classes he/she wishes to have joined. This relies upon the definition of Domains for (cont.) Data Items that are keys, components of keys, or foreign keys. The Domain definitions enable MAGEC to match-up foreign (cont.) keys with primary key fields of those Data Classes to which a join is possible. For example, if the Customer-Number (cont.) field in the Invoice record is defined as belonging to the same Domain as the Customer-Number field of the Customer (cont.) record, and that field is also the key to the Customer file, then MAGEC knows that it can use the Invoice's (cont.) Customer-Number to access the Customer file. Thus, the developer has three levels of automation to choose from to generate Logical Joins: 1) manual--do it using Cobol coding him/herself 2) semi-automated--let MAGEC do most of the work 3) fully-automated--let MAGEC do it all # Table Maintenance ## TOCxxx Functions MAGEC's Automatic Table Lookup Editing feature is used by both your application developers' generated MMP's and by the (cont.) MAGEC System MMP's as well. The Lookup Table feature supports up to 999 Tables that are identified by their Table (cont.) Numbers (001 thru 999). MAGEC reserves the use of Table # 200 thru 255 for "system use". Therefore, you may define up (cont.) to 744 of your own Tables for your applications. Each Table is defined by an entry in the "Table of Contents" (TOC). To list the TOC entries enter: TOCLOC 1 To add a new Table to the system enter: TOCADD ttt where: ttt = new Table number The screen will return to you asking for a DESCRIPTION and an ERROR NUMBER. The description is free-form. The Error (cont.) Number must be defined on the MAGEC Error file (ERR). It is the Error Number which will be displayed to the application (cont.) user when he/she mis-enters into a screen field that is being validated against this Table. We recommend that you use Error Numbers which correspond to the Table Number for which it applies. For example, Error (cont.) Number 001 for Table 001. However, remember that MAGEC reserves Error Numbers starting with a '9' for its own (cont.) use. ## TBLxxx Functions To list the entries (codes and descriptions) which make up any given Table, enter: TBLLST ttt where: ttt = Table Number To add a new entry to a given Table enter: TBLADD ttt/ccccccc where: ttt = Table Number ccccccc = the new Code (16 char. max.) You may similarly change the description for an entry using TBLCHG, or delete an entry entirely using TBLDEL.. You can (cont.) only display or add to a table number which has been defined via the TOCADD function described (cont.) above. The changes you make to the Tables take effect immediately and do not require you to use the **LOAD Function or to (cont.) recompile any program. Naturally, the MAGEC Security System governs access to the Table and Table of Contents (cont.) Functions. ## Where-Used for Tables Table Lookup validations are automatically done by MAGEC's reusable routines. They are triggered by the specifications (cont.) made for screen fields. In many cases it would be useful to know every reference to a given table; e.g. every screen (cont.) field that is validated against that table. This is especially important when grand changes are planned for that table (cont.) and you would like to determine the impact of those changes. To find every reference to a table you would use the online command: SCDTBL nnn where nnn = the table number in question You will receive a list of all screen fields which reference that table. If you press PF13, the list will be "spooled" for hardcopy printing. ## Field-level HELP for Table-edited Fields MAGEC's Field-level HELP facility is especially useful for screen fields that are validated against a table. If the (cont.) operator presses the PF2 key with the cursor pointing to such a field on the screen, MAGEC will display the usual (cont.) one-screen help text for that field plus a message saying that he/she can press PF8 to list the table's (cont.) entries. If the operator presses PF8 to begin scrolling through the entries of the table, he/she can then use the list on the (cont.) screen as a "pick list" by pointing with the cursor to a desired value and pressing ENTER. MAGEC will return to the (cont.) application screen with the selected value filled into the screen field. # Initializing Files Next: https://magec.com/DOC/markdown/db03.md.txt