**Level** is the Cobol level number of this item. **Data Name** is the Cobol dataname, a prefix of the element name is forced. **Sign **is "S" for signed numeric, blank for unsigned and non-numeric. **SIG** is the number of significant digits left of the decimal point. Must be "00" for alphanumeric items, may be "02" pr "04" for dates signifying number of digits in year (88 versus 1988). **Dec** is the number of decimal places, must be "00" for alphanumeric items. For dates this specifies the number of years old an acceptable date may be. **Comp **is "P" for packed decimal data, "B" for binary data, blank for non-numeric or zoned decimal data. **Edit Type** is the MAGEC type code as defined in the *Programmer's Reference Guide*. **Tbl **is the MAGEC lookup table number, valid for Edit Type "T" items only, otherwise must be zero. **Req** is "R" for a required item, "O" for an optional item. **Lgth** is the field's length in bytes (calculated automatically for numeric items). **Just **is "L" for left justified, "R" for right justified, default is left justified. **Redefines** is the dataname (standard prefix omitted) of the data item which this item redefines, blank if not applicable. **88-Val/Pattern** is the condition value (if this is an 88 level item), or the edit pattern if this is an Edit Type "P" or "#" item. **Domain Name** is the name (up-to 20 characters long) of the domain to which this data item belongs. Leave blank if (cont.) the data item does not belong to any domain. Domains are discussed later in this tutorial and in the "Database (cont.) Administration" chapter of your "Programmer's Reference" book.. **DataBase Identifier** is the up-to 20-character ID used by the SQL database. You can leave this blank if not using SQL, it will be ignored. **Data Item Narrative** is the 8-line descriptive text which will be presented to the application user when he or she (cont.) requests field-level HELP by pointing to a screen field and pressing the PF2 key on an application accessing this data (cont.) item. **Displacement / Length** is displayed for your information only, you cannot enter into these fields. They show the (cont.) displacement, relative to zero within the Element, and the number of bytes that this field occupies. ``` DITCHG VAD01/T/000050 ** M A G E C D a t a I t e m Element MAGEC Vacation Dummy data Field Seq#: 000050 Mode T Level: Data Name: Sig Dec Sign: Usage: 05 VAD01 DATE-HIRED PIC 9( 00 )V9( 00 ) EditType: m Tbl: 000 Req: Lgth: PIC X( 00006 ) Just: Occurs: 00000 Depending On: Redefines: 88-Val/Pattern: Prompt: Hire Date Domain Name: ____________________ DataBase Identifier: Data Item Narrative: Displacement / Length: This is the actual date that the employee was hired. It should always be_______ accurate if at all possible. Refer to the personnel records if necessary_______ to be sure._____________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ 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 Press PF24 for Pop-up Short List ``` Figure 13 — Data Item Definition Screen You should specify PROMPT's for the other fields, as well. This is not mandatory, but it is much nicer. A rule of thumb (cont.) might be to specify a PROMPT which is approximately the same length as the field. That will avoid wasted space on (cont.) reports since MAGEC must allow room for the larger of the field or its heading. Don't get too cryptic, (cont.) though. You might also wish to alter the Edit Types for the numeric fields and for the Employee Number (EMPNUM) field to improve their appearance on the screens and reports. You could refer to the *Programmer's Reference Guide* for a full description of the Edit Types and their meanings. For this project we recommend the following: For the numeric fields (not including EMPNUM) use the Edit Type "-" (the minus sign). This tells MAGEC that you wish leading zeros to be suppressed and that the value may be negative. For the EMPNUM data item we recommend that you use the Edit Type of "#" (pound sign). This tells MAGEC that it is a (cont.) numeric, pattern-edited field. The edit pattern is entered into the "Pattern" (also named "Initial Value" prior to (cont.) Release 2.0 of MAGEC). We suggest the Pattern of "999-99-9999" since the Employee Number is usually the same as Social (cont.) Security Number. This will tell MAGEC to format this 9-digit number onto screens and reports by inserting the dashes. (cont.) There are numerous other Patterns you could devise which might be equally valid. In order to get full benefit from the field-level HELP capabilities built into every online application, we recommend (cont.) that you enter a narrative for each DIT (with the possible exception of group items which will never be referenced and (cont.) FILLER's). Do this:** Scroll down to the Figure below. ``` DITCHG VAD01/T/000050 Data UPDATED on Database ** M A G E C D a t a I t e m Element MAGEC Vacation Dummy data Field Seq#: 000050 Mode T Level: Data Name: Sig Dec Sign: Usage: 05 VAD01 DATE-HIRED PIC 9( 02 )V9( 00 ) EditType: M Tbl: 000 Req: O Lgth: PIC X( 00006 ) Just: L Occurs: 00000 Depending On: Redefines: 88-Val/Pattern: Prompt: Domain Name: ____________________ DataBase Identifier: Data Item Narrative: Displacement / Length: This is the actual date that the employee was hired. It should always be_______ accurate if at all possible. Refer to the personnel records if necessary_______ to be sure._____________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ ________________________________________________________________________________ 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 Press PF24 for Pop-up Short List ``` Figure 14 — Data Item Change Screen After you have put your finishing touches on the dictionary definitions for the Data Items it is time to generate a new, MAGEC-standard COBOL definition. You use the DITGEN function to do that. Do this:** Key in the command: DITGEN VAD01 and press ENTER. The screen will look like the figure shown below. **Do this:** Verify that you spelled VAD01 right, press PF14 (Shift-F4 on PC) to continue. **Note:** If the access method specified in the DCL definition (first step in the data definition process) had been (cont.) either SQL or DB2, the DITGEN function would generate both the standard Cobol data definition copybook, plus an SQL (cont.) host variable definition copybook, plus the code to move data from the host variables to the Cobol definition and (cont.) vice-versa. When you generate an application accessing this data, MAGEC will automatically include these copybooks (cont.) where appropriate. **Note:** As of Release 3.0 of MAGEC the DITGEN function has the added task of generating the ASCII / EBCDIC (cont.) translation parameters for the Element. These parameters control the conversion of data which is being read or written (cont.) to another computer in a network when the two computers use dissimilar coding schemes. As it attempts to build these (cont.) parameters, which will be stored on the ELT record for the Element, it senses inconsistencies resulting from (cont.) redefinitions or incorrect lengths for group items. DITGEN will stop generation and display an error message when such (cont.) inconsistencies are detected. If you wish to ignore them and force DITGEN to proceed and generate the normal Cobol (cont.) definition without producing correct and valid translation parameters, press PF5 instead of PF14. We recommend that you not ignore any errors noted, even if you do not anticipate needing ASCII / EBCDIC translation. (cont.) You should go back to the DIT records and correct the errors. The purpose for PF5 is to enable you to revert to a less (cont.) thorough validation process which is identical to that employed in prior releases of MAGEC. ``` DITGEN VAD01 ** ================================================================================= _________________________________________________________________________________ To Generate (or Re-Generate) the CopyBook Press PF14 (or PF5 to ignore certain errors) (you must have Excl. Ctl. of the Element) Generated CopyBook will OVERLAY the old CopyBook - if one exists Member Name will be VAD01-C ``` Note:** The DITGEN function asks you to press PF14 to confirm that you really do want to re-generate the copybook. It (cont.) also shows ou the name of the copybook which wil be catalogued. If the access method is SQL, or DB2, other members will (cont.) also be generated. Figure 15 — DITGEN Screen MAGEC will generate the Cobol copybook and catalogue it to the MAGEC library for use in any program which accesses the (cont.) VAD01 Element. It will display the new copybook to you for verification. You do not need to do anything to the (cont.) generated copybook. Notice that the key field is highlighted with a marker in column 1 through 6. This signifies that that field name (cont.) matches the one specified on the KYF (key definition) as the Cobol Name for the key. The key field should never be a (cont.) numeric (PIC 9) type field and should be the same length as the specified key length (on the KYF). If MAGEC had sensed (cont.) a discrepency as it was generating the Cobol copybook, it would have issued an error message *it would have still generated the copybook, though.* The error message would be merely a warning. You could always review the specifications for the key using the command: KYFSEE VADK1   You can now exit MAGEC in preparation to submit the batch jobstreams to create and initialize the new file. **Do this:** Press PF15 to exit MAGEC. ``` LBRNXT VAD01-C//001 ** SEARCH ARG: .................................................................. Password: M A G E C VAD01-C page LIBRARY MEMBER (001) TAB Option: ON ....+..;10.;..+;..20....+...30....+...40...;+...50....+...60....+...70.. * * * THIS COPYBOOK GENERATED BY "DITGEN" 01 * * * FROM TEST VERSION 93/11/25 11:46:43 02 * * * PRIMARY KEY FIELD IS VAD01-KEY 03 04 VAD01-ELEMENT. PIC X(00198). 04 04 FILLER REDEFINES VAD01-ELEMENT. 05 KEY==> 05 VAD01-KEY. 06 06 VAD01-EMPNUM PIC 9(09). 07 06 VAD01-FILLER PIC X(00009). 08 05 VAD01-DATE-HIRED. 09 06 VAD01-DATE-HIRED-YY PIC XX. 10 06 VAD01-DATE-HIRED-MM PIC XX. 11 06 VAD01-DATE-HIRED-DD PIC XX. 12 05 VAD01-EARNED-VACATION PIC S9(05)V9(02) COMP-3. 13 05 VAD01-TAKEN-VACATION PIC S9(05)V9(02) COMP-3. 14 05 VAD01-EARNED-SICK-DAYS PIC S9(05)V9(02) COMP-3. 15 Move CURSOR to a line, use ERASE EOF to Delete it -or- PF20 to Insert After it Semicolon (;) is the TAB Character Asterisk (*) in col. 1 = suppress upcase ``` Figure 16 — Copybook in Library Note:** Now it is time to actually create and initialize your new file. If you are using a mainframe computer to do (cont.) this project you may wish to skip this step since there is little new to be learned from it. On a PC it is very easy to (cont.) create the file using the MAGINIT batch utility provided with MAGEC, therefore, you should go ahead and create (cont.) it. If you are using a mainframe you must execute IDCAMS with the appropriate control cards to DEFINE a cluster. Then you can execute MAGINIT to (cont.) initialize the file. Initialization is necesssary before you can access the file from CICS (or other TP Monitors). It (cont.) consists of opening the file "for output", writing a record to it, closing the file and (optionally) re-opening the (cont.) file and deleting the "initialization record". The JCL to execute MAGINIT is shown in the "Offline Utilities" chapter. You simply specify the new file using the DD (cont.) (or DLBL) for "NEWFILE". There are no control cards. If you are doing the project on a PC then you can simply execute (cont.) MAGINIT to both create and initialize the new file. At the DOS prompt, key the command "MAGINIT". The program will ask (cont.) you for the Data Class to be initialized, respond with "VAD" (excluding the quotes). **Do this:** Execute IDCAMS, then Submit MAGINIT. If you are using MAGEC on a PC with the Realia Cobol or Micro Focus Cobol compiler then the file MAGINIT.BAT is the jobstream you execute to both (cont.) create and initialize your new file. This file can be found in your \MAGEC\JCL (for Realia) or \MAGMF\JCL (for Micro (cont.) Focus) directory (depending on which Cobol compiler is installed) **Do this:** At the DOS prompt type the command MAGINIT VAD. **Note:** Appendix A of this tutorial tells you how to delete all of your work. You may wish to do the steps in Appendix A after you complete this project in order to clean up for the next student. # Database Utility ## DBDITO MAGEC includes a useful online utility program which allows you to do any database operation right from the screen. You (cont.) can display data, update data, add data, and delete data. You can enter in either character or in hexadecimal format. (cont.) Data is displayed in both formats simultaneously. **Do this:** Return to MAGEC via the "TS01" command and log on (if necessary). Once in MAGEC you must log on again (if you are told to do so), then you can use the online DBDITO utility. **Do this:** Key the command: DBDITO and press ENTER. The screen will look like the figure shown below. You can press, the HELP key (PF1, F1 on a PC) for instructions on how to use the DBDITO function. DBDITO is a very handy tool for debuggers, developers, and database administrators. It can help you in many ways: It can be used to find and correct bad records on a file It can be used to teach newcomers how the MAGEC database commands work It can be used to test your new/altered file definitions It can be used to create test data Next: https://magec.com/DOC/markdown/data05.md.txt