Similarly, all other fields within Element CUS02 would be named: CUS02-something-or-otherBecause of the Cobol limit on length of datanames "something-or-other" must not be longer than (cont.) 24 characters. Of course, it must also conform to all other Cobol restrictions regarding special characters, (cont.) etc. ## ELEMENT Group Each Element (ELT) must be defined by a copybook that is named according to the rules described earlier, e.g.: eeeee-C where: **eeeee** — = Element Name Furthermore, the first item in the copybook must have a Cobol level number greater than 03 since the copybook will be (cont.) included in the generated programs under the item named: 03 TWA-DB-DATA. We recommend that the first item in the (cont.) copybook be a group item which defines the entire Element and that it be defined as: 04 eeeee-ELEMENT where: **eeeee** — = Element Name We also recommend that it always be a Cobol level 04, as shown above. When you are defining the ELEMENT Group Item to the MAGEC Dictionary's DIT file you may let MAGEC automatically fill in (cont.) the proper length for you. If the Item's Cobol level is 04 and the dataname is ELEMENT then MAGEC will lookup the (cont.) length specified on the ELT file for that Element and place it into the length "PIC X ( )" (cont.) automatically. ## Date fields In order for the Automatic Editing feature and the MMP generator (MMPCREAT) to properly handle DATE fields we recommend that DATE fields always be defined as follows: ** 05 eeeee-xxxxxxxxxxxxxxxxxxxxx. ``` 06 eeeee-xxxxxxxxxxxxxxxxxxxxx-YY PIC XX. ``` ``` 06 eeeee-xxxxxxxxxxxxxxxxxxxxx-MM PIC XX. ``` ``` 06 eeeee-xxxxxxxxxxxxxxxxxxxxx-DD PIC XX. ``` where: eeeee** — = Element Name **xxxxx** — = up-to 21-characters of dataname **-YY** — = designation of field containing year **-MM** — = designation of field containing month **-DD** — = designation of field containing day For dates with the 4-digit year, another 2-byte item is inserted above the -YY item that is named with the suffix -CC , to contain the century portion of the 4-digit year. The generated MMP will automatically move each of the date's components individually so that the screen-image of the (cont.) date may be in some other format from that of the database field; e.g. MM/DD/YY, or DD/MM/YY. The MMP generator assumes (cont.) that you will adhere to this standard and will use the suggested suffixes and that each of the component fields will be (cont.) PIC XX, not PIC 99. ## Date fields on DIT definition When defining a Date field to the MAGEC Dictionary's DIT file it is not necessary for you to define the component (cont.) fields. You should simply specify "M", "D", or "Y" as the Edit Type to indicate that the Item is a Date field. MAGEC (cont.) will automatically calculate the proper length (either 6 or 8 bytes) for you. When you generate the Cobol copybook it (cont.) will automatically create the component fields for you. For date fields you use the specification for Significant (cont.) Digits (SIG) to indicate whether you desire a 2-digit year or a 4-digit year. An entry of 04 in the SIG specification (cont.) denotes a 4-digit year, and entry of 02 (or any other value) defaults to a 2-digit year. ## Master Key MAGEC requires that you include a single Data Item in your copybook which defines the Master Key (Primary Key) for the (cont.) file. There is no particular rule regarding the name for that Item. If the key is actually made up of multiple fields (cont.) then the Item defining the Master Key may be a group Item with the key component fields defined below it (cont.) as: ** 05 eeeee-MASTER-KEY. ``` 06 eeeee-xxxxxxx PIC ..... ``` ``` 06 eeeee-yyyyyyy PIC ..... ``` - etc. The data name MASTER-KEY is merely suggested, not enforced. The field should be either a group item or an alphanumeric (cont.) item, not a numeric (PIC 9) item. The component fields may be any type of data, numeric or (cont.) alphanumeric. When you defined the key definition (see KYFxxx functions) you specified the Cobol dataname of the key field. That name (cont.) should match the name used in the DIT definition for that key field. The length (in bytes) of the field should match (cont.) the length specified for the key in the KYF definition. If there is a discrepency, you will be issued a warning message (cont.) at the time you have MAGEC generate the Cobol copybook for the Element. ## Creating a Copybook You may use your preexisting Cobol copybooks in MAGEC-generated applications by simply cataloguing them to the MAGEC (cont.) library using the MAGECLBR batch utility program as explained earlier; or you may let MAGEC generate a Cobol copybook (cont.) for you from MAGEC Dictionary data. In order to have MAGEC generate your copybooks you must first define the Data Items (cont.) (DIT's) to the Dictionary. There are two ways you can define Data Items to the Dictionary: 1) by keying the definitions into the online Dictionary maintenance screens (DITxxx Functions). 2) by using another (cont.) special feature of the MAGECLBR utility program to "read" your old copybook and automatically create the Dictionary (cont.) definitions.If you use the second method you will probably also want to then use the online DITxxx Functions to look at (cont.) and possibly modify the Data Item definition since default values will have been used for some parameters which could (cont.) not be determined from the Cobol copybook.We strongly recommend that you use the MAGEC Dictionary to generate your (cont.) "copybooks" since having the Data Item definitions available to MAGEC (via the Dictionary) is required for a large (cont.) number of features and facilities that are either already implemented or are planned for future releases of MAGEC. We (cont.) will continue to support the facility to catalogue books using the "-MAGECADD LIB" contol card (as described in an (cont.) earlier topic); but we intend for it to be used only in those cases in which defining the data to the Dictionary is not (cont.) appropriate (such as WORKING-STORAGE areas, etc.). To define Data Items to the dictionary using your Cobol definition (cont.) (old copybook) as input you would use the "-MAGECADD DIT" control card in MAGECLBR. See the "Offline Utilities" chapter (cont.) for more detailed instructions regarding MAGECLBR. ## DITxxx Functions The standard set of nine Functions is provided for the MAGEC DIT file to accommodate adding, updating, inquiring, and (cont.) browsing. In addition, there are some extra Functions provided which allow you to resequence (renumber) the Data Items (cont.) of an Element, to list the Data Items of an Element on the screen, and to generate the Cobol copybook of the Element (cont.) using the DIT file definitions. The key format for the DIT file records is: eeeee/m/999999 where: eeeee** — = Element Name, 5 characters **m** — = Mode, T or P, test or production **999999** — = Sequence #, 6-digits The Mode defaults to T whenever it is omitted. As you can readily see you may have a Test and a Production set of (cont.) definitions for any given Element. As you can also see the sequence (order) of the Data Items is controlled by the (cont.) 6-digit sequence number. We suggest that when you are initially adding definitions for an Element's Items you increment (cont.) the numbers by 100 to facilitate insertions (a time-proven technique). If you reach the point where you have inserted a sufficient number of Items that you feel you are running out of (cont.) available numbers to be used for further insertions then you may use the DITSEQ Function to renumber the Data Items (cont.) (for that Element). DITSEQ will renumber in increments of either 10 or 100 (default = 100) allowing you to do more (cont.) insertions. Detailed instructions for using all the DIT Functions are available online via the HELP key (PF1) at any (cont.) time to anyone authorized to do the Function. Refer to the MAGEC Application User's Guide* for instructions as to how (cont.) to use the online documentation if you need to. The special Functions that are provided in addition to the nine standard ones are: DITLST list Data Items for an Element DITSEQ re-sequence Data Items for an Element DITGEN generate Cobol copybook for an Element You will be unable to add a Data Item until the Element to which it belongs has been defined on the ELT file (via (cont.) ELTADD). Further, you must get "Exclusive Control" of the Element (and all its Data Items) before you will be able to (cont.) do any form of database updating Function to the DIT file. See the Exclusive Control of ELT section of this (cont.) chapter. ## DIT Entry Formats The DIT Definition Screen is designed to resemble (as much as is possible) standard Cobol data definitions, including (cont.) the Cobol level number and PICture clauses. Of course; there are some parameters which MAGEC records for which there is (cont.) no Cobol equivalent, such as PROMPT. PROMPT is the desired column heading (for listings) or data entry prompt for 3270 (cont.) screen formats, it is used by MAGEC automatic screen painting and offline report generation. All of Cobol's data definition features are included except for the ones used by the "Report Writer" compiler option and 66 and 77-levels. ``` ** DITxxx EEEEE/M/999999 M A G E C Data Item Definition Element .............................. Field Seq#: ...... Mode . Level: Data Name: Sig Dec Sign: Usage: .. ..... ........................ PIC . 9( .. )V9( .. ) U D EditType: . Tbl: ... Req: . Lgth: PIC X( ..... ) Just: . Occurs: ..... Depending On: ........................ Redefines: ........................ 88-Val/Pattern: .................... Prompt: .................... Domain Name: .................... DataBase Identifier: .................... Data Item Narrative: Offset / Length: ..... / ..... ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ Press PF4 for browse (LOC) screen Press PF13 for Hardcopy Press PF16 to Copy field to buffer Press PF17 to Paste data from buffer Press PF2 for field-level HELP ** ``` Figure 04 — Data Item Definition Screen Element is a protected field which displays the Element description which comes from the definition on the ELT file. Field Seq# is a protected field displaying the sequence number portion of the key for this Data Item. Mode is a protected field which displays the test or production mode (T or P). Level is a required field that is the Cobol level number to appear in the generated copybook. It must be 04 thru 49 or 88. Data Name is the desired Cobol data name to be generated in the copybook. Maximum size is 24 characters. MAGEC will prefix this (cont.) name with the 5-character Element Name, plus a dash (-), giving a Cobol data name of up to 30 characters in the (cont.) copybook. Sig is the number of significant digits to the left of the decimal point (or implied decimal point) for numeric Data Items. (cont.) For Data Items that are dates (type M, D, or Y) this value specifies either a 02 or 04 to indicate a 2-digit or 4-digit (cont.) year (such as 88 versus 1988). For other (non-numeric) Items this value must be 00. Dec is the number of decimal places (to the right of the decimal point) for numeric Data Items. For dates this value (cont.) specifies the maximum age (in years) of a date that is to be accepted by the Automatic Editing. Sign is a code indicating whether this Data Item is to be defined with a "sign" (PIC S9, etc.) in the generated copybook (cont.) definition. A value of S indicates signed, a value of U indicates unsigned. For non-numeric Items this must be blank. (cont.) Numeric SQL data items must be signed. Usage is a code which specifies type of numeric data. It is only valid for numeric Data Items (as specified by the Type field (cont.) described above). A value of P indicates Packed (COMP-3). A value of B indicates Binary (COMP or COMP-4). A value of D (cont.) indicates Zoned Decimal (DISPLAY). Must be blank for non-numeric Data Items. Zoned Decimal illegal for (cont.) SQL. EditType is the MAGEC Automatic Editing Edit Type (such as N for numeric, or X for alphanumeric, or $ for numeric with (cont.) "$$,$$$.99" type Cobol editing, etc.) This is used as a default or suggested Edit Type when the developer references (cont.) this Data Item as a "Source/Target" field on the MSKDEF screen. It does not mean that the database copybook will (cont.) contain the Cobol edit pattern. The generated database Element copybook will use an appropriate data representation for (cont.) file data based upon this Type parameter and other parameters such as SIG, DEC, COMP, etc. Tbl is the Auto Edit Lookup Table number, if this is a type T item. Req is the Requirement code (R or O) to indicate that this Item is a Required entry on the Maintenance screen, or Optional. Lgth is the length (in bytes) of this Item. For numeric or date items MAGEC will calculate this for you. For alphanumeric (cont.) items you must enter the length here. If the Level is 04 and the Data Name is "Element" MAGEC will fill in the length (cont.) from the ELT file definition. Just is a code indicating that this Item is left justified or right justified. A value of L or R is accepted. If left blank L will be assumed. Occurs Next: https://magec.com/DOC/markdown/db05.md.txt