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