Introduction

Database Administration Tutorial

---

This tutorial is written primarily for use by those persons who will be using the MAGEC software to develop and maintain applications or to define (and maintain definitions of) files and databases to the dictionary.

Copies of this tutorial should be distributed to:

This chapter will teach you how to define data to the MAGEC Dictionary. To demonstrate the process most effectively, it uses a sample project based upon defining data similar to that used by the VAC system referenced in the MAGEC "Application Developer" tutorial.

This tutorial is written assuming that the reader is familiar with the overall MAGEC philosophy. It presumes that you understand how the "standard set of nine" functions work and that you are familiar with the standard screen formats of MAGEC. We suggest that you first read the MAGEC Application User's Guide, if you have not already.

This chapter has a tutorial format which guides you through the definition of an actual sample file. You might also wish to refer to other sections of the MAGEC Programmer's Reference Guide for more information relating to data definition, specifically:

These are not required reading, but they will help you to gain a more complete understanding of the MAGEC environment.

In this tutorial you will notice that there are many screen exhibits showing, step by step, exactly how each screen should look as you go through the exercise. You will also notice, preceding each exhibit, both descriptive explanations and concise commands. The commands tell you exactly what to do to accomplish the project. The rest of the text gives you a more complete understanding of what you are doing, and why, and how to get more information.

You may want to first go through this chapter following the tutorial exercise, doing the project as you go, skimming over the background explanations. Then you might re-read the chapter more slowly and completely to get greater understanding. This approach has proven very effective for many people.

In order to help you to discern the commands from the background as readily as possible, you will notice that they are enclosed in a box.

DO THIS: Commands look like this.

In this project you will define a new "file" to the MAGEC Dictionary. Actually, you will define a "dummy" which is modelled after the VAC Data Class used in the other tutorial projects. The purpose for this project is to teach you the steps necessary to define your own files to the Dictionary. This project should be done, or at least reviewed, by all Database Administrators and by all Application Developers. The Data Class you will define is the "VAD" (Vacation Dummy). The actual file name will be:

\MAGEC\VADK1.DAT (for PC MAGEC with Realia COBOL)

"MAGEC.VAD.CLUSTER" (for mainframe VSAM -- DD/DLBL Name = VADK1)

The file has one key (VADK1) which is the Employee number (9 digits) followed by nine bytes of blank padding a total of 18 bytes long. The file has two Elements, (VAD00 and VAD01). Element VAD00 is the 36-byte Audit Stamp, Element VAD01 is the actual data portion of the record.

If you are doing this project on a mainframe you may not wish to actually follow through with the execution of IDCAMS and so forth. On the PC, however, it is very simple to create the file using the MAGEC utility "MAGINIT", and then later to delete it using the DOS command "ERASE".

The procedure you will follow to define (and create) the new Data Class is:

1. Use DCLADD to define the Data Class.  

2. Use KYFADD to define the Key.  

3. Use ELTADD to define the Element(s).  

4. Use MAGECLBR to define the Data Items (fields).  

5. Use DITCHG to further tailor the Data Item definitions.  

6. Use DITGEN to generate a standard COBOL definition.  

7. Use MAGINIT to create and initialize the file (on PC)
or, use IDCAMS to create the file (on mainframe), then use MAGINIT to initialize it.  

8. Use DBDITO to test the new file (if you did step 7).  

NOTE:

• If this project has already been done by another student, you must first "undo" it before you can begin. To "undo" the project refer to Appendix A of this tutorial.

To begin, you must define the new Data Class to the MAGEC Dictionary.

DO THIS: Log on to MAGEC using: ID = 18, Password = ALEE.

DO THIS: Key the command: DCLADD VAD and press ENTER.

Your screen should look like the one shown here.

The Data Class definition gives MAGEC high-level specfications for the new file.

Data Class will be filled in by MAGEC, you do not enter anything into it.

Description is a 30-character free-form text field.

Critical File (Y or N) is yes or no specification as to whether this file is one of MAGEC's critical files. Specifying Y here will cause MAGEC to give this file priority when loading specifications into its in-memory tables in the event of a shortage of space. Your data files should almost always have N specified here, therefore, this parameter defaults to N.

Recording Mode may be F or V (fixed or variable).

Max Record Length may be up to 32,767.

Audit-Stamp specifies whether or not this file is to have a 36-byte portion (Element) of the record reserved for MAGEC to stamp "who", "when", and "where" this record was last updated (or added or deleted).

Real Delete specifies whether deletes to this file are to actually delete the record. If you specify N then the records will simply be flagged for deletion (pseudodeleted). The deletion flag is within the 36-byte Audit Stamp; therefore, you cannot specify N for Real Delete unless you have specified Y for Audit Stamp.

Data Base ID is for use only with Datacom/DB files, it should be 000 for all others.

Block Size is the physical block or control interval size.

Access Method specifies the type of file; for example: SQL, VSAM, DLI, or Datacom, etc.

Gateway Name specifies the name of the Gateway machine (as defined on MAGEC Lookup Table #248) which controls this Data Class. If MAGEC's TCP/IP networking facility is not installed this specification should always be left blank or set to "LOCAL". If a valid Gateway Name (from Table #248) is specified, MAGEC's I/O module will automatically pass any requests to read or write to this Data Class to the specified Gaterway machine. The results will be passed back.

The Data Class definition contains high-level information about the new file. You can refer to the Database Administration chapter of your MAGEC manual for detailed descriptions of each field on this screen.

DO THIS: Key in the specs as shown below, press ENTER.

If you have made any errors you will receive error messages and you can press the HELP key (PF1 on mainframe, or F1 on PC) for further assistance. Once you have corrected any errors your new DCL definition will be recorded and you will be transferred immediately to the Key Definition Screen.

If you are doing this project on a PC, you will still specify VSAM as the Access Method since MAGEC provides transparency, allowing you to treat indexed files on the PC exactly as if they were mainframe VSAM files.

The Key Definition Screen looks like the figure shown below.

After you have successfully added the new DCL definition (from prior page), you will automatically be presented the Key Definition Screen, as shown in Figure 03. It is prepared for you to immediately enter the specifications for the VADK1 key, the primary key for the VAD Data Class.

If your new file has alternate keys (subordinate keys), you may need to also define them. The "K1" suffix means that this key is the primary key (also called Master key). Alternate keys may be defined using suffixes of "K2" through "K9". If more than nine keys are needed you may define the rest using alphabetic "key numbers" (i.e. xxxKA thru xxxKZ); however, that would be very unusual and would require you to do some minor customization when you use this Data Class as the primary Data Class in applications.

The key may be subdivided into as many as five component fields. This allows your key field to be a group item which is broken down into elementary items. Each of the elementary (Component) fields can have its own set of attributes (max, min, type) to tell MAGEC how to normalize (edit and reformat) an operator's entry in order to construct the proper key for accessing the file. Every valid Cobol data representation is supported, as evidenced by the Field Type codes shown on the screen.

A detailed definition of each field on this screen is included in the "Database Administration" chapter of your MAGEC manual.

DO THIS: Continue to the Figure below..

NOTE:

• If the key being defined is an alternate key (not ...K1), there will be an additional specification prompted for on the KYFADD screen; it looks like:

Dup Key Flag: _ (Y = Duplicates Allowed)  

• Primary keys must not allow duplicate key values, alternate keys may or may not permit duplicate key values. This specification is not prompted for on the Primary key since the only possible setting would be "N".

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 9 type field, if your key is a single numeric field you should define a group item above it and specify that dataname 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 characters, in a VSE environment it may be up to 7 characters, in a PC environment it must be 5 characters (1 to 8 characters in MAGEC rel. 3.0 and later). The PC filespec consists of a path to the \MAGxx directory, the DD Name, and 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 specified to IDCAMS or AMSERV for VSAM files. It is relative to zero, not to one -- a key which starts at the beginning of the record starts at a displacement of 0000. Another way of remembering this is that the displacement is the number of bytes which are before the key in the record. In the VAD Data Class (file) our key is the next thing following the 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 editing rules for each field allows MAGEC to generate code in your programs to handle simplified user entry (omitted 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 or binary then the length in bytes will be smaller than the number of digits. This tells MAGEC both the maximum number of characters to accept and the number of characters to pad an operator's entry with if he/she enters fewer than the maximum.

Min specifies the minimum number of characters for each component field that you wish the operator to be required to enter. If Min is 0000 then he/she can omit that component and MAGEC will default to either zero or spaces depending 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 to convert the data into the proper internal format for use accessing the file. The valid types are listed on the 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 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 (key number 2, or greater) then there would be another parameter shown on the screen. The extra parameter is to specify whether or not duplicate key values are to be allowed. When you are defining a Primary key, that parameter is not shown and cannot be specified. MAGEC requires that the Primary key must not permit duplicates; i.e. must be a unique ID.

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 unit of transfer between the MAGEC I/O module and your programs. In some database environments the name "segment" 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 the physical attributes of your data files. For example: if you define three Elements for your customer master file record, one for the name and address data, one for the credit authorization data, and one for demographic data, then any given program can access (read, write) only those portions of the record which are specifically needed. A name and address display/update screen needs only access the first Element, it need not even be aware that the other two Elements exist. Another program might access both the name and address Element and the demographics Element, and so forth.

The advantage of doing this lies in the fact that you can then change the record, perhaps increasing the size of the credit authorization Element and adding more fields to it (thereby changing the physical record length as well), without having to recompile those programs which were not specifically accessing the credit authorization 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.

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 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 the next lower level data definitions, the Data Items (DIT's). This is to prevent multiple persons from updating the 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 applications accessing this Element. This enables you to restrict access to sensitive data, such as payroll or security files. A level of zero indicates that anyone who can develop applications can access this Element, the highest 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 installer and trainer to use until permanent ID's are setup for each user) you should enter 18 into the Employee Having Temporary Exclusive Control field. This prevents multiple persons from changing the Data Items (fields) for this Element at the same time (unless they are all logged on as the same ID). If you leave this field blank, MAGEC will automatically default to the employee number you logged on with.

DO THIS: Key in the specs as shown below, press ENTER.

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 updates to each record are made. The Audit Stamp Element is always named with a suffix of "00". That is a MAGEC 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 program is placing incorrect values into the database by inspecting the audit stamps of the records containing 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 others. When defining your pre-existing files to MAGEC, they need not be re-formatted to accommodate an Audit Stamp; just specify (on the DCL definition) that they do not have an Audit Stamp and then do not define a "00" element. Remember, you can access your existing files exactly as they are. Pre-existing programs can continue to access the same 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 the two elements we are defining (VAD00 is 36 bytes, VAD01 is 198 bytes) add up to only 234 bytes. This leaves 36 bytes of the physical record undefined. This is not an error! It is a legitimate practice to allow for anticipated expansion.

• We could later on define another element, say VAD02, which describes that unused 36-byte portion of the record. Doing so would not require us to alter, or even re-compile the programs which access VAD01 and/or VAD00. This is one aspect of how MAGEC provides data independence for our applications. Of course, this would also work if we had not left unused space, perhaps by having defined the physical record length as 234 bytes originally. Then, however, we would have to physically unload the data file, re-define the file to VSAM (or whichever access method is being used), reload the data to the newly defined (longer record length) file. We still would not need to touch any pre-existing programs since the 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 records to the file; therefore, the undefined portion will have a predictable content if/when you decide to put it to use.

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.

The Audit Stamp [in this case] is the first 36 bytes of the physical record. MAGEC does not require it to be the first 36 bytes, but most users define it that way for consistency. It might be a good idea if you followed that same procedure when defining files with Audit Stamps.

The Audit Stamp Element must be defined if the DCL definition specifies that this Data Class has an Audit Stamp, otherwise you will likely get a DB Error 99 (DB99) or Error 22 (DB22) at run-time when accessing this Data Class.

It is not necessary for you to define any Data Items (DIT's) for the Audit Stamp Element; MAGEC will use the predefined standard definition for it. All Audit Stamps have an identical definition. It is defined in the library member ELT00-C on the MAGEC library. To look at it you can enter the command:

LBRSEE ELT00-C  

To avoid unnecessary I/O overhead ordinarily associated with dictionary-driven systems, MAGEC loads compressed images of the dictionary data associated with file definitions and security into main memory. It uses highly optimized search algorithms to access that data. The data is originally loaded into memory when your online system is first brought up, or whenever the first transaction to MAGEC is sensed. You can cause MAGEC to reload this data dynamically in order to put new or changed definitions into effect immediately.

In order to tell MAGEC to refresh its in-memory images of the data definitions from the ones stored on the dictionary files, you must use the **LOAD command.

DO THIS: Key in the command: **LOAD as shown, press ENTER.

You can key in the command "**LOAD" from any screen. You do not need to first press the CLEAR key or blank out the other data on the screen, it will be ignored by the **LOAD program.

Next we must define the Data Items (DIT's) for the VAD01 Element. We will first use the batch MAGECLBR utility to populate the dictionary from an "old" COBOL definition, then we will use the online DITxxx functions to put the finishing touches on the definitions.

Exit MAGEC and go into your text editor.

DO THIS: Press PF15 to exit MAGEC.

Refer to the "Offline Utilities" chapter of your MAGEC manual for the proper JCL with which to execute MAGECLBR. JCL varies from one operating environment to another; however, the control card formats for MAGECLBR are the same in all environments.

If you are doing this project on a PC with the Realia, or Micro Focus Cobol version of MAGEC then you will find the "JCL" in the member named \MAGxx\JCL\MAGLBREX.BAT and the control cards (and data cards) will be placed into the \MAGxx\MAGECLBR.RDR member. You can access either of these using any PC editor. Many MAGEC users like the PC implementations of SPF which are available with the MAGEC system. In the above PC direcory names, \MAGxx stands for \MAGEC or \MAGMF, depending on which Cobol compiler is in use.

DO THIS: Key the control cards as shown below and submit.

NOTE:

• The **TRM** control card tells MAGECLBR to trim off the prefix "VDF-" from the datanames. MAGECLBR will automatically add a prefix of "VAD01-" as it adds the definitions to the dictionary.

The first item is named "ELEMENT", which is another MAGEC standard.

If you are using one of your own old COBOL definitions as input to MAGECLBR you should change the name of the first (group) item to "ELEMENT".

If your Cobol level numbers begin with numbers less than 04, MAGECLBR will bump the COBOL level numbers up so that they start with level 04 and above. This is because the data definitions will be included into the TWA under a level-03 item (TWA-DB-DATA).

The date field is defined as simply X(6). Later we will tell MAGEC that this field is a date by setting the "Edit Type", MAGEC will then generate the appropriate breakdown (YY, MM, DD) automatically.

NOTE:

• The -MAGECDEL card is to delete any pre-existing DIT definitions for the VAD01 Element (if they exist). If they do not exist [as in the first time you do this project on a newly installed system] then you should omit the -MAGECDEL control card.

• The Cobol definitions in the example (Figure 10) are in standard Cobol format and indented to Cobol norms (column 8, column 12, etc.). Virtually all valid Cobol definitions are acceptable; however, level-66 and level-77 items are not supported. Level-88 is supported. You should always review the generated definitions online to verify that they are correct and to add finishing touches (such as: Domain definitions, patterns edits, table validations, narrative descriptions, etc.). Always check the "printout" for error or warning messages, as well.

-MAGECDEL DIT VAD01
-MAGECADD DIT VAD01
**TRM**VDF-
  01  VDF-ELEMENT.
  02  VDF-KEY.
  03  VDF-EMPNUM  PIC 9(9).
  03  FILLER  PIC X(9).
  02  VDF-DATE-HIRED  PIC X(6).
  02  VDF-EARNED-VACATION  PIC S9(05)V9(02) COMP-3.
  02  VDF-TAKEN-VACATION  PIC S9(05)V9(02) COMP-3.
  02  VDF-EARNED-SICK-DAYS  PIC S9(05)V9(02) COMP-3.
  02  VDF-TAKEN-SICK-DAYS  PIC S9(05)V9(02) COMP-3.
  02  VDF-EARNED-COMP-DAYS  PIC S9(05)V9(02) COMP-3.
  02  VDF-TAKEN-COMP-DAYS  PIC S9(05)V9(02) COMP-3.
  02  VDF-COMMENT  PIC X(00050) OCCURS 3 TIMES.








NOTE:

• The -MAGECDEL card is needed only if there are existing DIT's for this element. It should not be used if there are none.

When you submit the MAGLBREX jobstream, the MAGECLBR program will read the input Cobol definition and will generate Data Item definitions (DIT's) into the dictionary for you. This is faster than manually entering each one online, though you could accomplish the same thing that way.

To submit MAGLBREX on a mainframe insert the control card(s) and data cards into the jobstream (named MAGLBREX) and submit it. On a PC the control cards must be placed into a text file (usually named \MAGxx\MAGECLBR.RDR), the SET SYS006 command in the .BAT file named MAGECLBR.BAT must specify the input file name (\MAGxx\MAGECLBR.RDR) and you must type the command "MAGLBREX" at the DOS prompt, or select the MAGECLBR icon from your Windows or OS/2 control panel. You can refer to the "Offline Utilities" chapter of the Programmer's Reference Guide for more information.

You should check the output listing from MAGECLBR to be sure that it completed correctly. If it did not, correct any errors and rerun.

To "get back into MAGEC":

DO THIS: Use "TS01" to re-enter MAGEC.

DO THIS: Log on as Employee# 18, Password: ALEE.

Next we will look at the generated definitions online.

When MAGECLBR adds the DIT definitions from your input Cobol definition it must take defaults and make determinations regarding the attributes of each data item based upon the Cobol PICTURE clause alone. These default attributes will, in all cases, operate; however, they may not always produce the most aesthetically pleasing results.

It is a common practice for MAGEC users to first use the MAGECLBR utility to accomplish the "grunt work" and then to refine the DIT definitions online using the "DITCHG" function. This enables them to specify such things as a Prompt (heading) literal and data formatting and editing rules to produce better looking screens and reports with a minimum of effort by the application developers.

DO THIS: Key the command: DITLST VAD01, press ENTER.

The screen will return to you with the Data Items for VAD01 listed and showing the level numbers and PICTURE's. You can now cursor-select any item by moving the cursor down to it's line and pressing ENTER to see it (or PF4 if you wish to change it).

Notice that the Cobol level numbers have been adjusted to comply with the MAGEC standard.

We would now like to modify the specifications for the DATE-HIRED data item. It was defined as a simple PIC X(6) field by MAGECLBR, we will alter that specification to tell MAGEC that this is actually a YYMMDD date field which we wish to have displayed on the screen(s) and report(s) in the format MM/DD/YY. This will also tell MAGEC to automatically validate any data entered into the screen(s) to update this field to ensure that it is a valid date. It will also tell MAGEC to automatically present to the application program(s) the Julian equivalent and Day-of-Week code for the Gregorian date on the screen. These help the applications programmers to add their own custom editing more easily, i.e. to verify that the date is not a weekend day, etc.

Cursor-select the DATE-HIRED field for update.

DO THIS: Position the cursor to the line where VAD01 DATE-HIRED is listed and press PF4.

The screen will now show all the specifications for the selected field. You can overtype any of the specs and press ENTER to change them.

NOTE:

• By positioning the cursor to a line on the DITLST screen, then pressing PF4, you will have selected that item for a CHG function. If instead of PF4, ENTER was pressed, then you will have selected that item for viewing, which is a SEE function. To then alter data on the screen you would need to key "CHG" over the "SEE" of "DITSEE" in the function area of the screen.

Change the Edit Type as shown to specify this field as being a date. An Edit Type of "M" indicates that it is to be displayed on the screen and on reports in the MM/DD/YY format, it is stored on the file in the YYMMDD format.

Also, enter a Prompt for the field. The prompt will be used as the "heading" for this field on reports and as the screen prompt for online displays and updates. If you do not specify a Prompt then MAGEC will generate one (as best it can) using the COBOL dataname as its basis.

DO THIS: Key in the Edit Type, Prompt,and Narrative as shown, press ENTER.

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 the data item does not belong to any domain. Domains are discussed later in this tutorial and in the "Database 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 requests field-level HELP by pointing to a screen field and pressing the PF2 key on an application accessing this data item.

Displacement / Length is displayed for your information only, you cannot enter into these fields. They show the displacement, relative to zero within the Element, and the number of bytes that this field occupies.

You should specify PROMPT's for the other fields, as well. This is not mandatory, but it is much nicer. A rule of thumb might be to specify a PROMPT which is approximately the same length as the field. That will avoid wasted space on reports since MAGEC must allow room for the larger of the field or its heading. Don't get too cryptic, 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:

In order to get full benefit from the field-level HELP capabilities built into every online application, we recommend that you enter a narrative for each DIT (with the possible exception of group items which will never be referenced and FILLER's).

DO THIS: Scroll down to the Figure below.

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 either SQL or DB2, the DITGEN function would generate both the standard Cobol data definition copybook, plus an SQL host variable definition copybook, plus the code to move data from the host variables to the Cobol definition and vice-versa. When you generate an application accessing this data, MAGEC will automatically include these copybooks where appropriate.

NOTE:

• As of Release 3.0 of MAGEC the DITGEN function has the added task of generating the ASCII / EBCDIC translation parameters for the Element. These parameters control the conversion of data which is being read or written to another computer in a network when the two computers use dissimilar coding schemes. As it attempts to build these parameters, which will be stored on the ELT record for the Element, it senses inconsistencies resulting from redefinitions or incorrect lengths for group items. DITGEN will stop generation and display an error message when such inconsistencies are detected. If you wish to ignore them and force DITGEN to proceed and generate the normal Cobol 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. 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 thorough validation process which is identical to that employed in prior releases of MAGEC.

MAGEC will generate the Cobol copybook and catalogue it to the MAGEC library for use in any program which accesses the VAD01 Element. It will display the new copybook to you for verification. You do not need to do anything to the generated copybook.

Notice that the key field is highlighted with a marker in column 1 through 6. This signifies that that field name matches the one specified on the KYF (key definition) as the Cobol Name for the key. The key field should never be a numeric (PIC 9) type field and should be the same length as the specified key length (on the KYF). If MAGEC had sensed 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.

NOTE:

• Now it is time to actually create and initialize your new file. If you are using a mainframe computer to do 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 create the file using the MAGINIT batch utility provided with MAGEC, therefore, you should go ahead and create 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 initialize the file. Initialization is necesssary before you can access the file from CICS (or other TP Monitors). It consists of opening the file "for output", writing a record to it, closing the file and (optionally) re-opening the 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 (or DLBL) for "NEWFILE". There are no control cards. If you are doing the project on a PC then you can simply execute MAGINIT to both create and initialize the new file. At the DOS prompt, key the command "MAGINIT". The program will ask 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 create and initialize your new file. This file can be found in your \MAGEC\JCL (for Realia) or \MAGMF\JCL (for Micro 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.

MAGEC includes a useful online utility program which allows you to do any database operation right from the screen. You can display data, update data, add data, and delete data. You can enter in either character or in hexadecimal format. 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

• It can be used to un-delete records (if they are pseudodeleted)

In the wrong hands, it can produce great damage. It is important that your security officer maintain tight control over access to this powerful function

NOTE:

• Figure 17 (below) is shown for EBCDIC systems. If you are doing the project on an ASCII machine (i.e. IBM PC or PS/2) you will see different hexadecimal codes corresponding to the display characters.

• The DBDITO display shows each display character with the hexadecimal value below it in vertical format. The SPACE character is X'40' in EBCDIC and it is X'20' in ASCII.

You can enter the MAGEC database commands right on the screen using DBDITO. You will see the results of the commands immediately.

DO THIS: Key in the LOCKY command as shown below, press ENTER.

The LOCKY command does a generic key "start browse". The key value will be taken from the "data area" of the screen (where character/hex is displayed over/under).

DBDITO Command:

The FILE portion of the command is where you specify the Data Class.

In the KEY portion you specify the name of the key.

In the ELEMENTS area you list the Elements you wish to read.

Commands which begin with "LOC" (such as LOCKY) only return the key value which was found. For more information on the DB commands, you can refer to Appendix B of this chapter, and the "Database Administration" chapter.

NOTE:

• The data is displayed in character/hex (over/under) format. If you were using DBDITO to update the data, you could enter in either character or hexadecimal, or in a combination of the two. To enter data in hexadecimal, you must type a dot (.) in the character position and the desired hex code in the two rows below the dot. If the character row (top row) contains any character other than a dot, DBDITO will accept it as the desired character and will compute its hexadecimal value and display it below. If the character row contains a dot, DBDITO will compute the character value for the hexadecimal code and will display it in the character row above the hex code. If the character is not displayable on a 3270, DBDITO will display a dot in that position. Spaces are displayed as dots, also.

• Type a dot in the character position if you want MAGEC to accept your input in hexadecimal below for that character. If the character position is any character other than a dot, MAGEC will accept the character, ignoring the hexadecimal value below it.

If there are no records on the file you will receive a message saying NO RECORD FOUND on the bottom of the screen. This is a normal circumstance if you access the file immediately following its initializtion (using MAGINIT). In mainframe environments the MAGINIT program can be modified to either leave one record (the initialization record) on the file, or to delete it. It is often convenient in a CICS environement to leave the initialization record on the file -- it can be deleted using any CICS program or using DBDITO.

The screen will be displayed showing the found key value from the file in the data area. It is shown in character/hex, over/under format. The figure shown below shows how the display might look. It shows the hexadecimal values in EBCDIC, as they might appear on a mainframe. On a PC you would see a similar screen with ASCII. DBDITO displays the character value on the top line of each row of data, unless the character is non-displayable. Then it displays a dot (.) in that position.

If you wanted to update the data you could key in the changes in character format on the top line, or in hex in the lines below. If you wish to update by keying in hex you must be sure that the character (top) line contains a dot in the positions where you want your hex entry to be taken. This allows you to key both character and hex into one screenful of data, saving keystrokes and translation difficulties. On the bottom of the screen DBDITO displays the access method and error messages (translation of the return code) if appropriate.

The DB command to update a record is "UPDAT". A list of the DB commands may be found in Appendix B of this tutorial. For additional detailed information on the DB commands (also referred to as MAGECIO commands) please refer to the "Database Administration" chapter .

DO THIS: See below.

MAGEC provides the means for you to define extended, complex editing of data which can involve multiple data items and even cross-file validations. This editing can be defined by the person defining the data to the dictionary and will then be automatically inserted into any applications generated which update the data. These edits are called "Business Rules".

Business Rules are routines coded in Cobol which may be as large as 15,000 lines of Procedure Division code plus 15,000 lines of Data Division code. They are associated with an Element. Whenever that Element is added or updated the Business Rule logic is invoked. While the primary purpose for coding Business Rules is to validate data before it is placed onto the files, there is actually no limitation to what you can do in this logic. It is perfectly legal to do I/O, even other updates or adds, in the Business Rule logic. Some examples of what you might do in the Business Rule logic are:

1)  

Verify that if Employee type is "salaried" and Location is Texas then Salary must be not less than $20,000 and not greater than $80,000.

2)  

Concatenate the first three digits of Zip Code with the two-character State code and use the result as a key to access the Zip-State cross-reference file to ensure that this is a valid Zip Code within this State.

3)  

If processing an "add" function, access the Control File to obtain the next available mod-11 Employee Number and plug it into the key for this new record to be added.

4)  

Verify that if the salary of the employee being updated is greater than $60,000, then the authorization level of the operator making this change/add must be greater than a certain predefined authorization level.

These are a few examples of the power of Business Rules. Even the limit of 15,000 lines is not really a limit, since you can include -MAGECINC control cards, each of which could expand to 15,000 more lines. The most common use for -MAGECINC's in Business Rules will be in the Data Division to include Element copybooks for I/O's done in the Procedure Division code for the Business Rule.

SInce this coding might very well be inserted into several applications, and since those applications might very well include -MAGECINC's for some of the same copybooks as are being called for in the Business Rule's Data Division coding, we recommend that you take advantage of the facility in MAGEC to specify that your -MAGECINC is to be expanded only if it is not elsewhere included in this same program. This avoids the nuisance of duplicate definitions and resulting need to qualify all references, and wasted space.

DO THIS: Key the command: RULADD VAD01/RULWORK, press ENTER

The way you tell MAGEC to do that is via the -IFUNIQUE control card immediately preceeding your -MAGECINC, as shown below:

-IFUNIQUE
-MAGECINC member/modifier  

This will cause the member named "member/modifier" to be included into the program only if it is not already included. This works even if the other -MAGECINC for that member appears after this one in the physical program listing. This facility is not restricted only to Business Rules, it may be used anywhere in any MAGEC application; however, we believe that you will avoid much trouble if you establish a standard of using the -IFUNIQUE in front of every Data Division -MAGECINC in your Business Rules.

You are adding the Data Division code for your Business Rule. The rule we will be adding will verify that the Employee Number being added to the VAD Data Class is a valid number defined on the SIF Data Class. This means that the SIF Data Class is the "master file" and that you may not have vacation data for an employee who is not defined on the SIF file.

Business Rules can consist of Data Division and/or Procedure Division coding. The modifier "RULWORK" signifies that this code is to be inserted into the Data Division; it will be the definitions of work areas needed by the procedural logic (which you will be adding next). You are specifying, in this example, that you wish the SIF01-C copybook included unless it has been included elsewhere in the program.

To add a Business Rule for our VAD01 Element:

DO THIS: Key the two lines of code shown below, press ENTER.

The code you have specified here will be inserted into the Data Division, in the TWA area of any MMP's generated to update Element VAD01. Since this is in the Linkage Section of your programs you must not use the Cobol VALUE clause. You must also remember that this code will be inserted immediately behind a Cobol data item which is at level 03; therefore, your work fields should be Cobol level 04 and below.

Since any given program might have several Business Rules inserted (because it updates several Elements), it would be wise to force the work fields you define to be unique so that they do not conflict with other data items in the program. One good standard would be to prefix them with the Element name followed by two dashes, i.e:

04 VAD01--WORK-FIELD PIC S9(5).  

That way you need not worry whether some other data item in the program might have the same name. Data Items in the Element definition always have a prefix of the Element name followed by one dash. This scheme will also help programmers to quickly recognize Business Rule work items.

Also keep in mind that these work fields will be in the TWA and will not be part of the VARIABLE-STORAGE area which is always initialized to LOW VALUES; therefore, it will be your responsibility to initialize these areas in your Procedure Division logic, if such initialization is necessary. The contents of these fields will be unpredictable upon entry to the Business Rule Procedural logic.

Next you will add the Procedure Division code for your Business Rule, as indicated by the modifier "RULPROC". Note that the two modifiers, RULWORK and RULPROC, are the only two modifiers allowed for Business Rules. If you omit the modifier MAGEC will default to RULPROC. If you attempt to specify some other modifier, you will receive an error message and be unable to add it to the dictionary.

This logic is calling the MAGEC I/O module to read the SIF01 Element into the SIF01-C copybook (the group data item defining the entire element is named SIF01-ELEMENT). If a NOT-FOUND return code is sensed then it sets the error flag and specifies an error number to be issued. This triggers the MMP logic to bypass the update (or add) of the VAD01 data and to send the screen with an error message instead.

The setting of error message numbers and of the master error flag is identical to the way it is done in the ordinary editing of the screen (in the %EDIT insertion point); except that this logic is not specifically associated to any one single screen or MMP. As a result, you must abide by certain limitation.

Never reference any screen field except the four standard fields which are always present on every screen (except that you can reference screen fields using MAGEC's Symbolic Screen Field References described later). They are: SFUNCT, SKEY, SCOMPL, and SERRMSG (and their associated control and attribute fields). In this example we are setting the error flag for the SKEY field (on line one of the screen) so that it will be highlighted.

Never PERFORM a paragraph outside of the Business Rule logic, except for the standard routines which are always present in all MMP's.

If you need to insert a paragraph name into your code, use one which will not conflict with others in the various programs in which this logic might be inserted. The easiest way to do that is to establish a standard of using paragraph names which have a prefix of:

BB6nn-eeeee--  

where:
nn               = any two-digit number

eeeee               = the Element name for which this logic applies

Note the two dashes after the Element name. This helps avoid conflicts with paragraph names from other Business Rules, programmer's custom coding, and standard MAGEC-generated code. The Business Rules are inserted into the BB600-BUILD-REC routine; hence, the BB6nn prefix.

DO THIS: Key the command: RULADD VAD01/RULPROC, press ENTER.

The screen appears ready for you to key in your code. To save you keystrokes and reduce errors, there is a proforma displayed on the screen. You can overtype all or part of it, using it as a fill-in-the-blanks model. If this proforma is not suitable for what you wish to do, there are many others available. You can press PF4 for a list of them and then cursor-select the one you would like.

DO THIS: Key in the code as shown below, press ENTER

The code you are keying in is the standard call to the MAGEC I/O module. You could refer to the "Database Administration" chapter of the Programmer's Reference Guide for more details about calling the I/O module. You will notice that the call to 'MAGECSET' is used to point the I/O module to the SIF01-ELEMENT area to read into. SIF01-ELEMENT is the group item which is in the SIF01-C copybook which was included in the RULWORK code.

Notice, also, that you are setting the 3270 attribute for the SKEY field to high-intensity (line 13 of the code). That is legal in a Business Rule since you can depend on SKEY being present on any MAGEC screen. Screen fields other than the standard MAGEC screen fields (which are on all screens) must not be directly referenced in Business Rules. See NOTE2 below for more about referencing screen fields.

The technique of setting an error number and performing the "CA100-" routine is identical to that used in coding custom editing for an MMP. In this example we assume that error number "9XX" is already defined in the dictionary. If it were not, you would need to define it using the function:

ERRADD 9XX  

You would then enter the short message (33 characters) which is to be displayed at the bottom of the screen, and the 4-line narrative explanation which will be presented if the user asks for help by pressing the HELP key. You can use the same error message definitions for your Business Rules as are being used for other types of editing.

NOTE1:

• The Business Rule is also a last chance to modify the data in the element before it is written to the file. This is handy for setting default values into some fields. It also can be a handy place to define the logic used to obtain a unique key for a new record add. This removes from the programmer the burden of coding it (perhaps in several programs), and also gives the database administrator greater control.

NOTE2:

• The code on lines 10 and 11 is using a symbolic reference to a screen field associated with the database field "VAD01-EMPNUM". You should refer to the Programmer's Reference Guide, to the "Database Administration" chapter for more information about symbolic screen field references. The -IFEXIST statement renders the symbolic reference conditional. That means that if there is no screen field associated with VAD01-EMPNUM, line 11 will become a comment (asterisk in column 7). If there is a screen field associated with VAD01-EMPNUM then line 11 will move E to its error-flag. In this way you can indirectly reference screen fiields within a Business Rule, even though you do not know what their names will be in the MMP's.

• Symbolic references to screen fields may be used by Application Developers in their customization coding, as well as by Database Administrators in coding Business Rules and Referential Integrity Rules They may be used only in coding for online applications -- batch programs do not have screen fields.

The Business Rule processing enables the DBA to ensure the integrity of data content in the database. It also enables him/her to prevent the addition of "subordinate" items (i.e. invoices) unless their "parent" items are defined (i.e. customers). This is important in order to preserve the referential integrity of the database. That means that items reference only valid, existing entities, rather than erroneous (non-existing) entities (invalid customer number).

In order to fully defend the referential integrity of the database, one more facility is needed. We must be able to ensure that the parent item (i.e. customer) does not get deleted if there are subordinates (invoices) on file referencing it. Therefore, MAGEC provides another type of rule logic which the DBA can provide, it is called a "Deletion Rule".

Deletion Rules are identified by the word "RULDELT", as compared to the Business Rules identified by the word "RULPROC". They are defined and maintained in exactly the same way.

The RULDELT logic will be inserted into the generated MMP's in the BB400-EDIT-FOR-DELETE paragraph which is performed just prior to the the actual delete operation. Setting the error flag will prevent the delete from taking place, just as it prevents the add or update from taking place in the RULPROC logic.

DO THIS: Key the command: RULADD VAD01/RULDELT, press ENTER.

The screen will appear ready for you to enter your code. A proforma will be shown on the screen. You can simply alter it to suit your needs. This saves keystrokes and minimizes errors.

If you need to add work areas into the Data Division you should use the RULWORK identifier as you would for a Business Rule.

DO THIS: Key in the code shown below, press ENTER.

The error number '91J' should already exist on the MAGEC ERR file. If it does not, you should add it via the command: ERRADD 91J

To see if it is already defined you could use the command:

ERRSEE 91J  

-- if it is on file, it will be displayed to you.

The restrictions which applied to Business Rules also apply to Deletion Rules. The only difference between them is where they are inserted in the logic of a generated MMP.

In the preceeding project you have defined and created a completely new Data Class (a VSAM file, in this example) from scratch. The process is the same for any other data you need to define to MAGEC. You can review this tutorial and/or the MAGEC "Database Administration" chapter whenever you need to define new files or databases.

We defined it in a "top-down" manner as:

To define the Data Class:

  DCLADD VAD

To define the Key:

 

  KYFADD VADK1

To define the two Elements:

 

  ELTADD VAD01  

  ELTADD VAD00

To define the Data Items

 

  MAGECLBR (-MAGECADD DIT VAD01 operation)

To customize the Data Items:

 

  DITCHG VAD01//.....

To generate a copybook:

 

  DITGEN VAD01

To add a Business Rule and Referential Integrity checking:

 

  RULADD VAD01//RULWORK  

  RULADD VAD01//RULPROC  

  RULADD VAD01/RULDELT  

As a Database Administrator or Data Administrator you will often find a need for concise, hardcopy documentation of your Data Classes' definitions and Where-Used references. MAGEC provides a batch utility program which produces just such a report.

The report navigates through the dictionary, gathering facts related to the Data Class in question. It checks for many potential error conditions (inconsistent definitions or usages), missing pieces, overlapping definitions, and other circumstances which should be called to your attention. It also produces a where-used report showing all references to the Elements as primary or secondary Data Classes by both online and batch programs.

At this time, the VAD Data CLass has no references it is not yet used by any application. Since a report of the VAC Data Class (which is used by MMP600 and MBP600B) would be more interesting than a report of the new VAD Data Class we just defined and created, we will produce a DCLDOC report for VAC. This will better demonstrate the usefulness of this report.

DO THIS: Execute DCLDOC using a control card of: DCLDOC VAC Refer to your "Offline Utilities" chapter for appropriate JCL for your particular environment. DCLDOC is executed using the .BAT file named DCLDOCEX if you are using a PC workstation.

Review the output report carefully. You may wish to establish a standard of printing this report after any major additions or changes to the Data Class definitions and keeping the printed report on file for your use and for use by developers and maintenance programmers.

When you were defining the Data Items (DIT's), you might recall we mentioned "Domains". We did not try to explain Domains at that time because we did not want to disrupt the flow of the tutorial project with a long discussion, which Domains certainly require. Now we will take the time to discuss them.

A Domain is a category, or class, of data items. As an example, ZIP-CODE might be the name of a Domain that you have defined; you might have specified that ZIP-CODE's all should be five digit numeric items with a prompt (heading) of "Zip:", you might also have keyed in a narrative explanation which applies to ZIP-CODE's, in general. 

Then you might specify that the data item named CUS01-ZIPCD is in the ZIP-CODE domain. You would do that by typing the Domain Name "ZIP-CODE" into the Domain Name specification on the DITxxx screen for the CUS01-ZIPCD data item. MAGEC will ensure that the specifications for CUS01-ZIPCD are compatible with the Domain definition; it will also default (copy) any specifications (i.e. Narrative, Prompt, etc.) which you have left blank. The Domain serves, therefore, as a model for zip code fields everywhere. You would likely have many other data items in other elements and files which are also in the ZIP-CODE domain. This mechanism ensures that all of them follow certain rules of conformity to one another.

It is not required that all data items within a Domain be defined identically, merely that they be compatible. For example, one ZIP-CODE might be packed, another binary, and another display numeric; all must be five digits and numeric, however. This ensures that you can use a Cobol MOVE from any one to any other without corrupting the data or your program. One possible exception is that it is legal for one ZIP-CODE item to be signed while another is not. You will receive a warning message when defining the data item telling you that a sign will potentially be lost when referencing this data item, but you can ignore the warning and accept the risk. This is done because signed numerics are often more efficiently accessed than unsigned numerics, and many people will specify signs even on items which can never be negative.

You may have noticed from the above explanation that a data item may be "subordinate" to both an Element and a Domain. Further, an Element may have several Data Items below it, and a Domain may have several Data Items below it. If you wished to change the rules for a given Domain, say to change ZIP-CODE from a five-digit to a nine-digit numeric, you would probably appreciate the ability to get a Where-Used report for that Domain. Fortunately MAGEC provides both online and hardcopy Where-Used reporting for Domains. Refer to the topic Suggestions Regarding Domains later in this chapter.

The diagram in Figure 26 will help to clarify the relationship between the various entities.

NOTE:

• Your Programmer's Reference Guide contains a discussion about Domains in its "Database Administration" chapter.

To define a Domain you use the DOMADD function. Domains are uniquely identified in the dictionary using a six-digit number, they also have a twenty-character name. To add a new Domain you would enter the online command:

DOMADD nnnnnn

where nnnnnn is the unique id number. If one already exists with that number, you will receive the usual "Duplicate" message displaying the existing Domain definition.

A Domain definition is very much like a Data Item definition, with a few exceptions:

The Domain Name is limited to twenty characters

The "Cobol level number" must always be 50 thru 65

There is no Cobol dataname.

You should always provide a Narrative description for Domains since it will be used as the default description for any Data Items belonging to that Domain. If, for example, you do not specify a narrative for the Data Item named CUS01-ZIPCD, when an operator presses the field-level help key (PF2) for a screen field which has CUS01-ZIPCD as its source/target, MAGEC will get the narrative from the ZIP-CODE domain definition.

When you are adding Data Item definitions you can also save some effort since MAGEC will copy most of the specifications from the Domain definition, if a Domain Name is specified for that Data Item. If you enter specifications which are different from the Domains, MAGEC will compare them for compatibility and disallow incompatible definitions.

Proper use of the Domain facility of MAGEC will enable MAGEC to further automate the application development processes, specifically the logical joining of files.

Consider the situation in which you have two Data Classes (files), as:

CUS Customer data
IVC Invoice data

Now, suppose that the key to the customer data was customer number, which was defined as a Data Item named "CUS01-CUSTNO". Also suppose that there is a Data Item in the invoice record named "IVC01-CUST", and that it contains the customer number. Further suppose that both these Data Items are defined as belonging to the Domain "CUSTOMER-NUMBER". MAGEC now has enough information to know that it can construct an exact key for the customer file by MOVE'ing IVC01-CUST to CUS01-CUSTNO; therefore, it can fully automate the logical join process when an application needs to access the invoice data and join customer data.

Logical joining can be done without any Domain definitions or usage; however, it involves more effort by the application developer to build the key used to access a file. Use of the fully automated joining via Domains also gives the Database Administrator better control over how data is accessed.

The process used to automatically join data can be repeated for many levels. Thus, after reading the Invoice data and then joining the Customer data to it, you could possibly use the ZIP code from the Customer data to join another file which is keyed by ZIP code, and so on. You can even concatenate data items from more than one file to build the key to access another file. This automatic logical join facility is potentially powerful enough to eliminate almost all manual coding of file accesses by programmers. It depends, however, on your properly defining and using Domain definitions.

We suggest that you should always try to identify and specify Domain Names for those Data Items which are part of (or all of) a record key. Likewise you should always try to specify (the same) Domain Names for foreign keys within your records. This will not only help automate application development, it will also give you excellent documentation of relationships between Data Classes. The Where-Used reports and screens will be much more valuable to you than if you haphazardly (or not at all) use Domains.

When designing new files/tables, you should give consideration to identifying Domains for as many of the new Data Items as possible. This will help you to ensure uniform definitions and usage. You should also try to apply those Domain definitions to your existing Data Items--the minimum you will gain is a knowledge of which ones are inconsistent, the maximum is global standardization.

The offline utility program, MAGECLBR, contains a function to report usage for any Domain Name. It also has a function to make any necessary alterations to all Data Items belonging to a Domain in order to make them compatible. This would enable you to, say, change ZIP-CODE from a 5-digit numeric to a 9-digit numeric GLOBALLY. Obviously, Element and record lengths might need to be adjusted after you did this. The control cards for MAGECLBR to produce a Where-Used report and to globally alter definitions are, respectively:

-MAGECUSE DOM dddddddddddddddddddd
-MAGECGBL DOM dddddddddddddddddddd  

Where ddddddddddddddddddddd is the Domain Name. The Where-Used report will note any inconsistencies without altering any definitions. You should use it whenever you have a question regarding any given Domain.

You can get a quick online Where-Used display for any Domain by simply displaying its definition (using DOMSEE), and pressing PF6. The information will not be as thorough as from the hardcopy report from MAGECLBR, but it is often sufficient and it is much handier to obtain.

When adding Domain definitions, remember that they are identified by a six-digit unique number, and that the numbers from 000001 through 000100 are reserved for "figurative constant" or "literal" Domains, which have special meaning for the automatic logical join process.

MAGEC Software has plans to implement additional features which are to be driven by these Domain definitions in future releases of MAGEC. Your input and ideas will be appreciated.

For a number of reasons this project, and the other turorial projects, are best done on a microcomputer, rather than on a mainframe. Being the sole user of the system allows you to do things which would be very un-neighborly on a multi-user mainframe. If you are doing this project on a PC or PS/2 using the PC version of MAGEC, you might be able to simply re-install part of MAGEC's dictionary to delete the VAD definitions. Using the initial installation diskettes you could, at the DOS prompt, enter the commands:

C:
CD\MAGEC
RESTORE A: DCLK1.DAT
RESTORE A: KYFK1.DAT
RESTORE A: ELTK1.DAT
RESTORE A: ALGK1.DAT

This assumes that your \MAGEC directory is on the C: drive and that the diskettes are on the A: drive; you may need to adjust the above for your particular situation.

Whether you are using a PC or mainframe you can un-define the VAD Data Class. To delete all definitions for the sample VAD Data Class and all subordinate entities:

In all environments:

Online, in MAGEC, do the following functions:

DITPUR VAD01

LBRPUR VAD01-C

RULPUR VAD01

ELTDEL VAD00

ELTDEL VAD01

KYFDEL VADK1

DCLDEL VAD

On a PC:

Also, issue the following command from the DOS prompt:

ERASE C:\MAGEC\VADK1.DAT

The following is a list of DB Commands which may be used with DBDITO. For more detailed information, please refer to the MAGECIO Commands topic in the "Database Administration" chapter (section, Accessing Files from Programs).

COMMAND FUNCTION

REDKY read record for key value in the screen data area

REDNX read the next record from the one just read

REDPR read the previous record (not on Datacom DB)

REDID re-read the record just read

RDUKY same as REDKY but with intent to update

RDUID same as REDID but with intent to update

RDUNX same as REDNX but with intent to update

LOCKY locate record with key = or > the screen data area

LOCKX locate record with key = the screen data area

LOCNX locate next record from one just read or located

FSTAT test file status (open or closed, etc.)

REDLE read the record just located

UPDAT update the record

DELET delete the record

RELES release the record just read-with-intent

ADDIT add a record

• Datacom/DB supports all of the above commands plus a list of additional ones. If you are accessing a Datacom/DB file/database, you can use any legal command and it will be passed through to Datacom's DBENTRY entry point and the results displayed to you.

When you define your mask using MSKDEF, or when you modify it after having allowed the auto-paint feature to generate it for you, you can specify to MAGEC that you desire automatic editing to be done to screen fields. You do this by specifying, for each field, an edit type code.

These same edit type codes are also specified in the dictionary definitions for data items (DIT's). When you use the auto-paint feature (for online screens) or the automatic report program generation (as in the "Batch Developer" Tutorial) MAGEC sets the screen or report editing formats based upon the edit type codes found in the DIT definitions. You can override them in the MSKDEF or RPTDEF functions if you need to.

There are three general categories of edit types:

The Cobol copy book for a mask or the detail line definition for a report will contain appropriate Cobol edit patterns (ie. ZZZ.99-) based on the edit type. You might refer to the chapter, "Analysis of the Generated MMP" (found in the Programmer's Reference Guide) for more detail.

For numeric fields there is also a specification as to how many digits left of the decimal point and right of the decimal point are allowed.

One of the alphanumeric types is "T", that means table lookup validation. Operator entries will be validated by looking them up in a MAGEC lookup table. You can define lookup tables and the valid entries in those tables. Refer to the MAGEC "Database Administration" chapter for further details about lookup tables.

b Same as X.

A Alphabetic (A-Z and blank) characters only. Example: person's name, city name.

U Uppercase. Any characters will be accepted as valid, lowercase alphabetics will be converted to uppercase by MAGEC.

T Table lookup. Same as U plus MAGEC will validate entry against a lookup table.

W Where to display a description from a lookup table. Used in conjunction with a T field. MAGEC moves the description from the found entry in the table to a W field.

P Pattern edited alphanumeric field.

S Numeric, MAGEC will suppress leading zeros.

= Same as S, plus trailing minus sign.

Z Same as S, plus comma insertion.

-  (hyphen) Same as Z, plus trailing minus sign.

$ Same as Z, plus floating dollar sign.

# Pattern edited numeric field.

D DD/MM/YY or DD/MM/CCYY (2 or 4-digit year).

Y YY/MM/DD or CCYY/MM/DD (2 or 4-digit year).

NOTE:

• When the operator enters data into screen fields MAGEC accepts any valid, unambiguous format depending upon the edit type. For instance, in a type-$ field the operator may enter:

12345.5 or,
1,234.50 or,
$1,234.50 etc.

Sometimes you might wish to abend an online task issuing an error message to the operator. This is useful when you wish to cause Transaction Backout to be invoked, or when you just want to stop processing because your program has sensed error conditions beyond its capacity to deal with.

This can be accomplished easily via the ABEND command which is handled in MAGEC's I/O module.

To use the ABEND command, code:

MOVE 'ABEND' TO TWA-DB-REQUEST.  

MOVE xx TO TWA-DB-RETURN-CODE.  

MOVE 'mmmmm' TO SCOMPL.  

PERFORM AA840-CALL-MAGEC-IO THRU AA899-EXIT.  

In the above example, xx is a two-character abend code which you may set. MAGEC will abend the task issuing a CICS abend code of MUxx (MU is for MAGEC USER ABEND). The mmmmm is any 40-character message you would like displayed.

NOTE:

• Control passes to the I/O module which aborts the task. Control does not return to your program. If an Abend Handler program has been specified for either your MMP (refer to the definition of the "Screen Header" in the Application Developer Tutorial) or for the User View (refer to the discussion of "Global Parameters" in the Installation Guide), then the Abend Handler program will be invoked. Since you can code an Abend Handler program, it might do anything you desired--including return control to any program you choose.