B = Binary Numeric ``` Note:** The Component field definitions tell MAGEC how to edit the operator's key entry on a screen and how to convert (cont.) it into the proper format for reading the file. If the file is remote and its Gateway machine uses a different coding (cont.) scheme (ASCII / EBCDIC ), then these specifications also help MAGEC to properly translate a key value based upon the (cont.) data types for the component fields. Figure 03 — Key Definition Screen The fields on the Key Definition Screen are: **Description **is used to help the operator to understand what he/she is expected to enter as a key; it should be user-friendly and helpful, not a Cobol dataname. **COBOL Name** is the actual dataname of the key field (or group item) in the Cobol copybook. It should never be a PIC (cont.) 9 type field, if your key is a single numeric field you should define a group item above it and specify that dataname (cont.) in this Key Definition. **DD Name** is the external name that this file is known by to the environment. In an MVS environment it may be up to 8 (cont.) characters, in a VSE environment it may be up to 7 characters, in a PC environment it must be 5 characters (1 to 8 (cont.) characters in MAGEC rel. 3.0 and later). The PC filespec consists of a path to the \MAGxx directory, the DD Name, and (cont.) an extension of .DAT. **Drive ID** is the alphabetic drive designator, for PC or Network installations, on whcih this file resides. It may be left blank and will default to the LANDRV setting. **Displacement** is the starting position of the key in the physical record, it should exactly match what you have (cont.) specified to IDCAMS or AMSERV for VSAM files. It is relative to zero, not to one -- a key which starts at the beginning (cont.) of the record starts at a displacement of 0000. Another way of remembering this is that the displacement is the number (cont.) of bytes which are before the key in the record. In the VAD Data Class (file) our key is the next thing following the (cont.) 36-byte Audit Stamp. **Length** specifies the length of the key in bytes. **Component Fields** are up to 5 contiguous elementary data items which, concatenated, make up the key. Individual (cont.) editing rules for each field allows MAGEC to generate code in your programs to handle simplified user entry (omitted (cont.) leading zeros, trailing blanks) and to handle mixed data types among the component fields. **Max** specifies the number of characters or digits in each component field. If the component field is packed decimal (cont.) or binary then the length in bytes will be smaller than the number of digits. This tells MAGEC both the maximum number (cont.) of characters to accept and the number of characters to pad an operator's entry with if he/she enters fewer than the (cont.) maximum. **Min** specifies the minimum number of characters for each component field that you wish the operator to be required (cont.) to enter. If Min is 0000 then he/she can omit that component and MAGEC will default to either zero or spaces depending (cont.) on the type of field it is. **Type** specifies whether MAGEC is to pad with leading zeros (numeric) or trailing spaces (alphanumeric) and also how (cont.) to convert the data into the proper internal format for use accessing the file. The valid types are listed on the (cont.) screen. **Do this:** Key in the specs as shown below, press ENTER. After you have correctly entered the specs and the new Key definition has been added to the Dictionary MAGEC will (cont.) automatically transfer you to the screen to add an Element definition for the Element "VAD01" **Dup Key Flag**. The key we are defining here is a Primary key, key number 1. If you were defining an alternate key (cont.) (key number 2, or greater) then there would be another parameter shown on the screen. The extra parameter is to specify (cont.) whether or not duplicate key values are to be allowed. When you are defining a Primary key, that parameter is not shown (cont.) and cannot be specified. MAGEC requires that the Primary key must not permit duplicates; i.e. must be a unique (cont.) ID. ``` KYFADD VADK1 Enter data to be ADDED ** M A G E C Data Dictionary Key Definition Key Name ..... Description: Employee# (9-digits)________ COBOL Name: VAD01-KEY________________________ DD Name VADK1___ Drive ID (PC Only) _ Displacement: 36__ Length: 18__ Dup Key Flag: N (Y = Duplicates Allowed) ---------------------------Component Fields----------------------------- Field 1 Field 2 Field 3 Field 4 Field 5 max min type max min type max min type max min type max min type 9_ 2_ N 9_ 0_ A __ __ _ __ __ _ __ __ _ Field Types A = AlphaNumeric N = Zoned Decimal Numeric WITHOUT Sign Z = Zoned Decimal Numeric WITH Sign F = Packed Numeric WITHOUT Sign P = Packed Numeric WITH Sign B = Binary Numeric ``` NOTE: PC Users!** The Drive ID may be left blank. MAGEC will default to the drive specified in the SET LANDRV statement (cont.) for your environment (refer to *MAGEC Installation Guide*, PC-MAGEC Installation). If you specify an alphabetic drive (cont.) letter here, MAGEC will access the file on the specified drive. If you are running on a distributed network, you canhae (cont.) your files on various dirves and servers as you desire. The LANDRV setting establishes the default drive--it is also (cont.) needed to tell MAGEC where to find its own repository files. Figure 04 — Key Definition Screen # Element Definition ## ELTADD The Element definition screen looks like the one shown below. A detailed definition of each field can be found in the "Database Administration" chapter of your MAGEC manual. An Element is a portion of the physical record. It may also be called a "Logical View" of the record's data. It is the (cont.) unit of transfer between the MAGEC I/O module and your programs. In some database environments the name "segment" (cont.) describes a similar concept to the Element concept. By intelligently subdividing the physical record into several Elements you can insulate your programs from changes to (cont.) the physical attributes of your data files. For example: if you define three Elements for your customer master file (cont.) record, one for the name and address data, one for the credit authorization data, and one for demographic data, then (cont.) any given program can access (read, write) only those portions of the record which are specifically needed. A name and (cont.) address display/update screen needs only access the first Element, it need not even be aware that the other two (cont.) Elements exist. Another program might access both the name and address Element and the demographics Element, and so (cont.) forth. The advantage of doing this lies in the fact that you can then change the record, perhaps increasing the size of the (cont.) credit authorization Element and adding more fields to it (thereby changing the physical record length as well), (cont.) without having to recompile those programs which were not specifically accessing the credit authorization (cont.) Element. Also, to further reduce the potential for errors, you can request a "where used" report showing which programs do access the Element which you have changed (or intend to change). **Do this:** Continue to screen shown below. ``` ELTADD VAD01 Enter data to be ADDED ** M A G E C Data Element Definition Data Dictionary Maintenance Element (Segment)= VAD01 data-class .................................. Description: ___________________________________ test production Displacement: _____ _____ Length: _____ _____ DEVELOPER AUTH. - BATCH : _ DEVELOPER AUTH. - ONLINE: _ Employee having temporary Exclusive Control: _________ _______________ ______________________ ``` Figure 05 — Element Definition Screen The VAD Data Class will have two Elements, VAD00 is the 36-byte Audit Stamp, VAD01 is the vacation and other related data. The fields on this screen are: Element (Segment)** is filled in by MAGEC, you do not enter anything here. **Data Class** is filled in by MAGEC, you do not enter here. **Description **is a 30-character free-form text field. **Displacement ** is the "offset" (relative to zero) into the physical record for the start of this Element. Another (cont.) way of expressing that is: the number of bytes which precede this Element in the record. **Length**** **is the length of this Element, in bytes. **DEVELOPER AUTH - BATCH** is the authorization level required to develop batch applications accessing this Element. **DEVELOPER AUTH -ONLINE** is the authorization level required to develop online applications accessing this Element. **Employee having temporary Exclusive Control** is the employee number of the person who will be modifying or adding (cont.) the next lower level data definitions, the Data Items (DIT's). This is to prevent multiple persons from updating the (cont.) same set of records in the dictionary at the same time. The employee's name will be displayed below. First we will define the VAD01 Element, it begins at a **Displacement** of 36 (relative to zero) and is 198 bytes long (**Length**). Notice that there is a test and a production definition. This allows you to have different definitions in test mode and in production mode. In this example they are the same. The **authorization levels** for a batch developer and an online developer control who can create batch and online (cont.) applications accessing this Element. This enables you to restrict access to sensitive data, such as payroll or security (cont.) files. A level of zero indicates that anyone who can develop applications can access this Element, the highest (cont.) authorization level is 9. Since you have (probably) logged onto MAGEC using the ID number of 18 (the ID which is provided with MAGEC for the (cont.) installer and trainer to use until permanent ID's are setup for each user) you should enter 18 into the **Employee (cont.) Having Temporary Exclusive Control** field. This prevents multiple persons from changing the Data Items (fields) for (cont.) this Element at the same time (unless they are all logged on as the same ID). If you leave this field blank, MAGEC will (cont.) automatically default to the employee number you logged on with. **Do this:** Key in the specs as shown below, press ENTER. ``` ELTADD VAD01 Enter data to be ADDED ** M A G E C Data Element Definition Data Dictionary Maintenance Element (Segment)= VAD01 data-class .................................. Description: MAGEC Vacation Dummy data__________ test production Displacement: 36___ 36___ Length: 198__ 198__ DEVELOPER AUTH. - BATCH : 0 DEVELOPER AUTH. - ONLINE: 0 Employee having temporary Exclusive Control: 18_______ _______________ ______________________ ``` NOTE1 = The Developer Authorization Levels for both Batch and Online will default to "0" if you do not enter another (cont.) value into them. The Employee having temporary Exclusive Control will default to the Employee number you are logged (cont.) onto MAGEC with (18, Bobbie Lloyd, in this project). Figure 06 — Element Definition Screen When you pressed ENTER on the preceeding screen, you added a new Element definition for VAD01 to the dictionary. VAD01 is the 198-byte vacation data portion of the record. Now you will define the 36-byte Audit Stamp where MAGEC will record Who, When, with Which program, and Where all (cont.) updates to each record are made. The Audit Stamp Element is always named with a suffix of "00". That is a MAGEC (cont.) convention. Note:** A suffix of "00" specifically means to MAGEC that this Element is an audit stamp. MAGEC assumes that it is always to be 36 bytes in length. Having it defined otherwise will cause problems. The Audit Stamp is useful for detecting fraudulent accesses and for investigating errors. You can often determine which (cont.) program is placing incorrect values into the database by inspecting the audit stamps of the records containing (cont.) incorrect data. An Audit Stamp must always be defined as a 36-byte Element (if you have specified that this Data Class has an Audit Stamp in the DCL definition). **Note:** The Audit Stamp is an *optional* feature of MAGEC which you may specify for some Data Classes, and not for (cont.) others. When defining your pre-existing files to MAGEC, they need not be re-formatted to accommodate an Audit Stamp; (cont.) just specify (on the DCL definition) that they do not have an Audit Stamp and then do not define a "00" element. (cont.) Remember, you can access your existing files exactly as they are. Pre-existing programs can continue to access the same (cont.) files with no changes. **Do this:** Key in the command: ELTADD VAD00, press ENTER. The screen which is displayed now should look like the one shown in Figure 07. Now see below for instructions to fill in this screen. **Note:** In this tutorial you may have noticed that the physical record length (see DCLADD screen) is 270 bytes, while (cont.) the two elements we are defining (VAD00 is 36 bytes, VAD01 is 198 bytes) add up to only 234 bytes. This leaves 36 bytes (cont.) of the physical record undefined. This is not an error! It is a legitimate practice to allow for anticipated (cont.) expansion. We could later on define another element, say VAD02, which describes that unused 36-byte portion of the record. Doing (cont.) so would not require us to alter, or even re-compile the programs which access VAD01 and/or VAD00. This is one aspect (cont.) of how MAGEC provides data independence for our applications. Of course, this would also work if we had not left unused (cont.) space, perhaps by having defined the physical record length as 234 bytes originally. Then, however, we would have to (cont.) physically unload the data file, re-define the file to VSAM (or whichever access method is being used), reload the data (cont.) to the newly defined (longer record length) file. We still would not need to touch any pre-existing programs since the (cont.) programs never knew the record length in the first place. MAGEC's I/O module automatically initializes any undefined areas of the physical record to spaces whenever you add (cont.) records to the file; therefore, the undefined portion will have a predictable content if/when you decide to put it to (cont.) use. ``` ELTADD VAD00 ** M A G E C Data Element Definition Data Dictionary Maintenance Element (Segment)= VAD00 data-class .................................. Description: __________________________________ test production Displacement: _____ _____ Length: _____ _____ DEVELOPER AUTH. - BATCH : _ DEVELOPER AUTH. - ONLINE: _ Employee having temporary Exclusive Control: _________ BOBBIE LLOYD ``` Figure 07 — Element Definition Screen This Element definition is similar to the one you just did for Element VAD01. Do this:** Key in the specs as shown below, press ENTER. Next: https://magec.com/DOC/markdown/data03.md.txt